> For the complete documentation index, see [llms.txt](https://docs.terminal.africa/tship/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads.md).

# Sample Webhook Event Payloads

The exact JSON delivered to your endpoint for every webhook event, grouped by resource.

Every webhook includes `event` and `data`. Pickup webhooks also include a stable `event_id` and `occurred_at`; their `data.version` supports ordering and reconciliation.

```javascript
{
    "event": "shipment.delivered",
    "data": { }
}
```

The request also carries an `X-Terminal-Signature` header, an HMAC-SHA512 of the raw body keyed with your secret key. Always verify it before acting on a payload — see [Handling Webhook Events](/tship/miscallaneous/webhook-events/handling-webhook-events.md).

### What `data` contains

It depends on the event, and the difference matters:

* **Resource events** — `address.*`, `packaging.*`, `insurance.*`, `claim.*`, `transaction.*` — carry the resource itself, in the same shape the corresponding `GET` endpoint returns.
* **Shipment status events** — `shipment.in-transit`, `shipment.delivered`, `shipment.updated`, `shipment.cancelled`, `shipment.returned`, `shipment.awaiting-clearance`, `shipment.pending-cancellation` — carry a **lean tracking snapshot**, not the whole shipment. Addresses and the parcel appear as ids rather than embedded objects. If you need the full shipment, call [Get Shipment](/tship/shipment/get-shipment.md).
* **`shipment.created`** carries a fuller shipment object than the status events.
* **`shipment.customs_event`** and the `regulatory_document.*` events carry a small purpose-built object rather than a resource.
* **Pickup events** carry a versioned pickup snapshot, recovery instructions and a stable event ID. See [Pickup Events](/tship/miscallaneous/sample-webhook-event-payloads/pickup.md).

### Delivery behaviour

* The payload is **snapshotted at dispatch time** and stored. Replaying a webhook resends that stored snapshot — it is not rebuilt from the resource as it stands now, so a replay shows you what was originally sent.
* Keys whose value is undefined are omitted rather than sent as `null`. Treat every field below as optional and code defensively.
* Label bytes, internal storage keys and carrier blobs are never included. Documents appear as URLs.

### Payloads by resource

| Resource                                                                                         | Events                                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Address](/tship/miscallaneous/sample-webhook-event-payloads/address.md)                         | `address.created`, `address.updated`, `address.deleted`                                                                                                                                                                  |
| [Packaging](/tship/miscallaneous/sample-webhook-event-payloads/packaging.md)                     | `packaging.created`, `packaging.updated`                                                                                                                                                                                 |
| [Pickup](/tship/miscallaneous/sample-webhook-event-payloads/pickup.md)                           | `pickup.scheduled`, `pickup.booked`, `pickup.updated`, `pickup.completed`, `pickup.cancelled`, `pickup.failed`                                                                                                           |
| [Shipment](/tship/miscallaneous/sample-webhook-event-payloads/shipment.md)                       | `shipment.created`, `shipment.updated`, `shipment.in-transit`, `shipment.delivered`, `shipment.cancelled`, `shipment.returned`, `shipment.awaiting-clearance`, `shipment.pending-cancellation`, `shipment.customs_event` |
| [Insurance](/tship/miscallaneous/sample-webhook-event-payloads/insurance.md)                     | `insurance.pending`, `insurance.success`, `insurance.failed`                                                                                                                                                             |
| [Claim](/tship/miscallaneous/sample-webhook-event-payloads/claim.md)                             | `claim.success`, `claim.failed`                                                                                                                                                                                          |
| [Transaction](/tship/miscallaneous/sample-webhook-event-payloads/transaction.md)                 | `transaction.success`, `transaction.failed`                                                                                                                                                                              |
| [Reconciliation](/tship/miscallaneous/sample-webhook-event-payloads/reconciliation.md)           | `reconciliation.flagged`, `reconciliation.billed`                                                                                                                                                                        |
| [Regulatory Document](/tship/miscallaneous/sample-webhook-event-payloads/regulatory-document.md) | `regulatory_document.pending`, `regulatory_document.uploaded`, `regulatory_document.complete`                                                                                                                            |

{% hint style="info" %}
You can trigger any of these against your own data with [Simulate Webhook](/tship/webhooks/simulate-webhook.md), rather than waiting for the real event.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.