> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.goshippo.com/feedback

```json
{
  "path": "/docs/Tracking/WebhookMetadata",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Webhook metadata

> Attach custom metadata to transactions and tracking objects to include your own data in Shippo webhook payloads.

## Webhook metadata

Metadata is additional information you can include in many Shippo objects.
For some of these objects (`transaction`, `shipment`, and `batch`), this metadata can be very useful when handling webhook notifications because it allows you to associate your own custom data with the Shippo objects.

The following example shows how to use metadata with a transaction and the resulting webhook payload that is created.

### Create a `transaction_created` webhook

If you do not have one already, create a webhook with event type **Transaction Created** following the [setting up and testing webhooks](/docs/Tracking/Webhooks#setting-up-and-testing-webhooks) guide.

### Create a transaction

Purchase a label by calling the `transactions` endpoint. Include the field `metadata` with a string containing your additional information.

```shell Create transaction request theme={null}
url --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'SHIPPO-API-VERSION: 2018-02-08' \
--data-raw '{
  "rate": "a5c9d1bec93149f5bedc3a9374b50970",
  "async": false,
  "label_file_type": "PDF",
  "metadata":"customer_ID:12, order_ID:558a"
}'
```

### Webhook payload

The Shippo API will send a webhook payload to your URL including the `metadata` you configured in your transaction.

```json theme={null}
{
  "event": "transaction_created",
  "test": true,
  "data": {
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2024-06-17T14:31:40.000Z",
    "object_updated": "2024-06-17T14:31:40.000Z",
    "object_id": "70ae8117ee1749e393f249d5b77c45e0",
    "object_owner": "mrshippo@shippo.com",
    "test": true,
    "rate": "fe9a78973c5b409498af1fd9baefbe34",
    "tracking_number": "ZW70QJC",
    "tracking_status": "UNKNOWN",
    "eta": "2024-06-22T14:31:40.347Z",
    "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=ZW70QJC",
    "label_url": "https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    "commercial_invoice_url": "",
    "messages": [],
    "order": "7535a41cac64426fa87ebfa24ad11123",
    "metadata": "customer_ID:12, order_ID:558a",
    "parcel": "faf460225c4d49699e18384dc32a1cc6",
    "billing": {
      "payments": []
    }
  }
}
```

On receiving the webhook, you can parse the metadata and use it to update your system, notify users, or trigger other actions. For example, you might use this update to send an automated email to your customer to keep them up to date. This is a common pattern for parcel tracking. The Shippo API also supports metadata in webhooks for [tracking labels purchased outside of Shippo](/docs/Tracking/Tracking#adding-metadata).

You can use metadata in this way for any of the [supported webhook event types](/docs/Tracking/Webhooks#webhook-event-types).

### Webhook metadata for tracking

Metadata from a transaction does not get passed to your tracking webhook payload. You can add metadata to an existing tracking object by re-registering your tracking webhook.

Use the `tracking_number` from your transaction response along with your `carrier` and `metadata`. This `metadata` will be included in all webhook payloads associated with tracking updates for this `tracking_number`.

```shell theme={null}
 curl https://api.goshippo.com/tracks/ \
  --header "Authorization: ShippoToken <API_TOKEN>" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "carrier": "usps",
    "tracking_number": "9205590164917312751089",
    "metadata": "Order 000123"
 }'
```