> 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](https://docs.terminal.africa/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.tracking_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](https://docs.terminal.africa/tship/shipment/get-shipment.md).
* **`shipment.tracking_updated`** adds `data.tracking_change` with the previous and replacement waybill numbers, replacement label link and correction reference. See [Shipment payloads](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/shipment.md).
* **`connected_account.weight_discrepancy.detected`** carries a detection summary with the connected-account reference, comparison weights, invoice-verification flag and detection service fee. See [connected-account weight discrepancy detection](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/shipment.md#connected-account-weight-discrepancy-detection).
* **Hub issue events** carry the shipment's whole [`hub_issues`](https://docs.terminal.africa/tship/shipment.md#the-hub-issues-object) object, with the `change` and the `issue_ids` the event is about. See [Hub Issue Events](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/hub-issue.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](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/pickup.md).

### Delivery behaviour

* The payload is **snapshotted at dispatch time** and stored. Replay preserves the original business snapshot rather than rebuilding it from the current resource. Current security redaction still applies before sending.
* 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](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/address.md)                                                           | `address.created`, `address.updated`, `address.deleted`                                                                                                                                                                                               |
| [Packaging](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/packaging.md)                                                       | `packaging.created`, `packaging.updated`                                                                                                                                                                                                              |
| [Pickup](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/pickup.md)                                                             | `pickup.scheduled`, `pickup.booked`, `pickup.updated`, `pickup.completed`, `pickup.cancelled`, `pickup.failed`                                                                                                                                        |
| [Connected account](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/shipment.md#connected-account-weight-discrepancy-detection) | `connected_account.weight_discrepancy.detected`                                                                                                                                                                                                       |
| [Shipment](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/shipment.md)                                                         | `shipment.created`, `shipment.updated`, `shipment.tracking_updated`, `shipment.in-transit`, `shipment.delivered`, `shipment.cancelled`, `shipment.returned`, `shipment.awaiting-clearance`, `shipment.pending-cancellation`, `shipment.customs_event` |
| [Hub issue](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/hub-issue.md)                                                       | `hub_issue.reported`, `hub_issue.updated`, `hub_issue.reminder`                                                                                                                                                                                       |
| [Insurance](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/insurance.md)                                                       | `insurance.pending`, `insurance.success`, `insurance.failed`                                                                                                                                                                                          |
| [Claim](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/claim.md)                                                               | `claim.success`, `claim.failed`                                                                                                                                                                                                                       |
| [Transaction](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/transaction.md)                                                   | `transaction.success`, `transaction.failed`                                                                                                                                                                                                           |
| [Reconciliation](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/reconciliation.md)                                             | `reconciliation.flagged`, `reconciliation.billed`                                                                                                                                                                                                     |
| [Regulatory Document](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/regulatory-document.md)                                   | `regulatory_document.pending`, `regulatory_document.uploaded`, `regulatory_document.complete`                                                                                                                                                         |

{% hint style="info" %}
Use [Simulate Webhook](https://docs.terminal.africa/tship/webhooks/simulate-webhook.md) against your own resources to exercise your receiver. Simulation of `shipment.tracking_updated` reads the shipment snapshot; it does not create a replacement waybill or synthesize `tracking_change`. Use the illustrative [re-label payload](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/shipment.md) to test that field before a real correction.
{% 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.
