> 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/webhook-events.md).

# Webhook Events

Here you can find a list of webhook event types along with descriptions of each event.

These are every event type you can subscribe a webhook to. For the exact JSON delivered with each one, see [Sample Webhook Event Payloads](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads.md).

| Event                                             | Description                                                                                                                                                                     |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *address.created*                                 | This event is triggered when a new address is created.                                                                                                                          |
| *address.deleted*                                 | This event is triggered when an address is deleted.                                                                                                                             |
| *address.updated*                                 | This event is triggered when an existing address is updated.                                                                                                                    |
| *claim.failed*                                    | This event is triggered when a filed insurance claim is unsuccessful.                                                                                                           |
| *claim.success*                                   | This event is triggered when a filed insurance claim is successful.                                                                                                             |
| *connected\_account.weight\_discrepancy.detected* | This event is triggered when a qualifying weight discrepancy is detected for a shipment processed through an enabled connected account.                                         |
| *hub\_issue.reported*                             | A drop-off hub raised something about a shipment: a problem it found, a correction to the booking, or a repackaging fee. `data.hub_issues` carries every issue on the shipment. |
| *hub\_issue.updated*                              | A hub issue already reported changed: approved, declined, expired, withdrawn by Terminal, or a problem resolved.                                                                |
| *hub\_issue.reminder*                             | An approval is still waiting a day after it was asked for.                                                                                                                      |
| *insurance.failed*                                | This event is triggered when a purchase for insurance coverage fails.                                                                                                           |
| *insurance.pending*                               | This event is triggered when insurance coverage is initiated for a shipment.                                                                                                    |
| *insurance.success*                               | This event is triggered when insurance coverage is successfully purchased for a shipment.                                                                                       |
| *packaging.created*                               | This event is triggered when a new packaging is created.                                                                                                                        |
| *packaging.updated*                               | This event is triggered when packaging information is updated.                                                                                                                  |
| *pickup.scheduled*                                | A pickup record has been created and is awaiting carrier booking.                                                                                                               |
| *pickup.booked*                                   | The carrier or rider booking is confirmed, including an automatic replacement rider.                                                                                            |
| *pickup.updated*                                  | Collection progress or the shipments on a pickup changed.                                                                                                                       |
| *pickup.completed*                                | Collection completed; Priority Pickup completes at the hub, before onward shipment delivery.                                                                                    |
| *pickup.cancelled*                                | Collection has ended. Read next\_action for drop-off, scheduling or support instructions.                                                                                       |
| *pickup.failed*                                   | A pickup attempt failed or needs support. Read next\_action and retry to distinguish automatic recovery from terminal failure.                                                  |
| *reconciliation.billed*                           | This event is triggered when a weight discrepancy is billed on a shipment.                                                                                                      |
| *reconciliation.corrected*                        | This event is triggered when a weight discrepancy charge is corrected — either reversed in full, or reversed and re-billed at a corrected amount.                               |
| *reconciliation.flagged*                          | This event is triggered when a weight discrepancy is flagged on a shipment.                                                                                                     |
| *regulatory\_document.complete*                   | This event is triggered when every regulatory document required for a shipment is complete.                                                                                     |
| *regulatory\_document.pending*                    | This event is triggered when a regulatory document is required and has been requested for a shipment.                                                                           |
| *regulatory\_document.uploaded*                   | This event is triggered when a regulatory document is uploaded against a shipment.                                                                                              |
| *shipment.awaiting-clearance*                     | This event is triggered when a shipment is held awaiting customs clearance.                                                                                                     |
| *shipment.cancelled*                              | This event is triggered when a shipment is cancelled.                                                                                                                           |
| *shipment.created*                                | This event is triggered when a new shipment is created.                                                                                                                         |
| *shipment.customs\_event*                         | This event is triggered when a customs delay is detected on a shipment, and again when that delay is resolved. The `status` field in the payload distinguishes the two.         |
| *shipment.delivered*                              | This event is triggered when a shipment is delivered. e.g, Shipment delivered to destination address                                                                            |
| *shipment.in-transit*                             | This event is triggered only once when a new shipment is in-transit.                                                                                                            |
| *shipment.pending-cancellation*                   | This event is triggered when cancellation has been requested on a shipment but not yet confirmed by the carrier.                                                                |
| *shipment.returned*                               | This event is triggered when a shipment is returned to the sender.                                                                                                              |
| *shipment.tracking\_updated*                      | A hub parcel correction replaced the carrier waybill. The shipment ID stays the same; `tracking_change` identifies the previous number, replacement number and label link.      |
| *shipment.updated*                                | This event is triggered when an active shipment is updated. e.g. Shipment is picked up by rider.                                                                                |
| *transaction.failed*                              | This event is triggered when the transaction charge for a shipment fails.                                                                                                       |
| *transaction.success*                             | A wallet charge succeeded, including an additional charge captured for an approved hub parcel correction. The transaction identifies the related shipment.                      |

### Pickup recovery events

Pickup events share one contract for Priority and Scheduled Pickups. The envelope also includes `event_id` and `occurred_at`, and `data.version` increases for each new event. Read `next_action` to determine whether to wait, drop off, schedule again or contact support. A carrier-cancelled rider can be retried automatically; the pickup is only terminally cancelled when collection has ended. See [Pickup Workflow](https://docs.terminal.africa/tship/guides/pickup-workflow.md) for the recovery flow.

See [Pickup Event Payloads](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/pickup.md) for examples of each event.

### Hub issue events

Hub issue events carry the shipment's whole `hub_issues` object, with `data.change` saying what happened, so a missed delivery is caught up by the next one. Keep the one with the latest `hub_issues.as_of`. Read `hub_issues.action` to see what waits for an answer and by when. See [Hub Issues Workflow](https://docs.terminal.africa/tship/guides/hub-issues-workflow.md) for answering and processing them.

See [Hub Issue Events](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/hub-issue.md) for examples of each event.

### Hub parcel corrections

Hub Relabelling is being prepared for rollout. When enabled, subscribe to `shipment.tracking_updated` to receive replacement waybill details, and `transaction.success` for any correction charge captured from your wallet. A re-label can happen without an additional charge; a price-only correction can be charged without changing the waybill. See [Shipment payloads](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/shipment.md), [Transaction payloads](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/transaction.md#hub-correction-charges) and the [Changelog](https://docs.terminal.africa/tship/changelog.md).

### Connected-account weight discrepancy detection

Subscribe explicitly to `connected_account.weight_discrepancy.detected` on an active webhook to receive these alerts. The connected account must also have weight discrepancy detection enabled; existing webhook subscriptions are not automatically updated. Each detected shipment attracts a USD 0.02 service fee, independently of webhook subscription. The alert is provisional delivery-tracking evidence and does not confirm a carrier invoice adjustment.

See the [payload and eligibility rules](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/shipment.md#connected-account-weight-discrepancy-detection) and [subscription examples](https://docs.terminal.africa/tship/webhooks/create-webhook.md#add-the-event-to-an-existing-webhook).


---

# 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/webhook-events.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.
