> For the complete documentation index, see [llms.txt](https://docs.shipbubble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shipbubble.com/api-reference/webhooks.md). # Webhooks Shipbubble sends a payload to notify your application each time there is a status change on any of your labels (shipments). The payload for each webhook event will include information about the related API response. Your provided endpoint should be set up to receive an HTTP POST request and must always return a 200 HTTP response within 15 seconds of the request; otherwise, it will be marked as failed. In the case of a failed webhook, we’ll send a webhook every 5 minutes for the first 5 tries. {% hint style="info" %} #### VERIFYING WEBHOOKS WITH SHIPBUBBLE SIGNATURE To prevent your application from a replay attack, we recommend that you verify all webhook events by checking for our unique signature, **x-ship-signature**, in the request headers of our webhooks. We hash each webhook message that we send to your URL using HMAC (Hash-based Message Authentication Code) with the SHA512 algorithm and API\_KEY as the key of the hash {% endhint %} ### Events Shipbubble sends webhook events to notify you of changes in your shipment process. Here are some of the event types we send; we'll update the list as we release more actions in the future**.**
EventDescription
shipment.label.createdWhen a new shipping label is created.
shipment.status.changedWhen the status of your shipment changes
shipment.cancelledWhen your shipment is cancelled
shipment.cod.remittedWhen payment for a cash-on-delivery order has been remitted to your account
shipment.sla.updatedWhen the delivery eta time is updated, a delay_reason is added the payload as well
shipment.waybill.updatedWhen a new waybill or tracking code is generated for a shipment
wallet.threshold.alertWhen your wallet balance is equal to or below the threshold you've set. It will only go out if a threshold has been set in your dashboard
wallet.auto_topup.succeededWhen your wallet is topped up by any of our auto debit functions
wallet.auto_topup.failedWhen we try to top up your wallet and there is a failure, a reason is also present in the payload
{% tabs %} {% tab title="shipment.label.created" %} ```json { "event": "shipment.label.created" "order_id": "SB-6BAD4363F17C", "status": "pending", "courier": { "name": "Darum NG", "email": "darum@darum.com", "phone": "010000038198", "tracking_code": "2232", "tracking_message": "Tracking code: 14815206", "rider_info": null }, "ship_from": { "name": "Lebron James", "phone": "+2348057575855", "email": "lebron@james.com", "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria" }, "ship_to": { "name": "Lebron James", "email": "lebron@james.com", "phone": "+2348057575855", "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria" }, "to_be_processed": "2022-09-11T12:03:46.000Z", "payment": { "shipping_fee": 630, "currency": "NGN" }, "package_status": [{ "status": "Pending", "datetime": "2022-09-11T12:03:46.000Z" }], "insurance": null, "events": [], "dropoff_station": null, "pickup_station": null, "tracking_url": "http://localhost:3000/orders/tracking/SB-6BAD4363F17C", "waybill_document": null, "date": "2022-09-11T12:03:46.000Z" } ``` {% endtab %} {% tab title="shipment.status.changed" %} ```json { "event": "shipment.label.created" "order_id": "SB-6BAD4363F17C", "status": "pending", "courier": { "name": "Darum NG", "email": "darum@darum.com", "phone": "010000038198", "tracking_code": "2232", "tracking_message": "Tracking code: 14815206", "rider_info": null }, "ship_from": { "name": "Lebron James", "phone": "+2348057575855", "email": "lebron@james.com", "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria" }, "ship_to": { "name": "Lebron James", "email": "lebron@james.com", "phone": "+2348057575855", "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria" }, "to_be_processed": "2022-09-11T12:03:46.000Z", "payment": { "shipping_fee": 630, "currency": "NGN" }, "package_status": [{ "status": "Pending", "datetime": "2022-09-11T12:03:46.000Z" }], "insurance": null, "events": [], "dropoff_station": null, "pickup_station": null, "tracking_url": "http://localhost:3000/orders/tracking/SB-6BAD4363F17C", "waybill_document": null, "date": "2022-09-11T12:03:46.000Z" } ``` {% endtab %} {% tab title="shipment.cancelled" %} ```json { "event": "shipment.label.created" "order_id": "SB-6BAD4363F17C", "status": "pending", "courier": { "name": "Darum NG", "email": "darum@darum.com", "phone": "010000038198", "tracking_code": "2232", "tracking_message": "Tracking code: 14815206", "rider_info": null }, "ship_from": { "name": "Lebron James", "phone": "+2348057575855", "email": "lebron@james.com", "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria" }, "ship_to": { "name": "Lebron James", "email": "lebron@james.com", "phone": "+2348057575855", "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria" }, "to_be_processed": "2022-09-11T12:03:46.000Z", "payment": { "shipping_fee": 630, "currency": "NGN" }, "package_status": [{ "status": "Pending", "datetime": "2022-09-11T12:03:46.000Z" }], "insurance": null, "events": [], "dropoff_station": null, "pickup_station": null, "tracking_url": "http://localhost:3000/orders/tracking/SB-6BAD4363F17C", "waybill_document": null, "date": "2022-09-11T12:03:46.000Z" } ``` {% endtab %} {% tab title="shipment.cod.remitted" %} ```json { "event": "shipment.label.created" "order_id": "SB-6BAD4363F17C", "status": "pending", "courier": { "name": "Darum NG", "email": "darum@darum.com", "phone": "010000038198", "tracking_code": "2232", "tracking_message": "Tracking code: 14815206", "rider_info": null }, "ship_from": { "name": "Lebron James", "phone": "+2348057575855", "email": "lebron@james.com", "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria" }, "ship_to": { "name": "Lebron James", "email": "lebron@james.com", "phone": "+2348057575855", "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria" }, "to_be_processed": "2022-09-11T12:03:46.000Z", "payment": { "shipping_fee": 630, "currency": "NGN" }, "package_status": [{ "status": "Pending", "datetime": "2022-09-11T12:03:46.000Z" }], "insurance": null, "events": [], "dropoff_station": null, "pickup_station": null, "tracking_url": "http://localhost:3000/orders/tracking/SB-6BAD4363F17C", "waybill_document": null, "date": "2022-09-11T12:03:46.000Z" } ``` {% endtab %} {% tab title="shipment.sla.updated" %} ```json { "event": "shipment.label.created" "order_id": "SB-6BAD4363F17C", "status": "pending", "courier": { "name": "Darum NG", "email": "darum@darum.com", "phone": "010000038198", "tracking_code": "2232", "tracking_message": "Tracking code: 14815206", "rider_info": null }, "ship_from": { "name": "Lebron James", "phone": "+2348057575855", "email": "lebron@james.com", "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria" }, "ship_to": { "name": "Lebron James", "email": "lebron@james.com", "phone": "+2348057575855", "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria" }, "to_be_processed": "2022-09-11T12:03:46.000Z", "payment": { "shipping_fee": 630, "currency": "NGN" }, "package_status": [{ "status": "Pending", "datetime": "2022-09-11T12:03:46.000Z" }], "insurance": null, "events": [], "dropoff_station": null, "pickup_station": null, "tracking_url": "http://localhost:3000/orders/tracking/SB-6BAD4363F17C", "waybill_document": null, "date": "2022-09-11T12:03:46.000Z" } ``` {% endtab %} {% tab title="shipment.waybill.updated" %} ```json { "event": "shipment.label.created" "order_id": "SB-6BAD4363F17C", "status": "pending", "courier": { "name": "Darum NG", "email": "darum@darum.com", "phone": "010000038198", "tracking_code": "2232", "tracking_message": "Tracking code: 14815206", "rider_info": null }, "ship_from": { "name": "Lebron James", "phone": "+2348057575855", "email": "lebron@james.com", "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria" }, "ship_to": { "name": "Lebron James", "email": "lebron@james.com", "phone": "+2348057575855", "address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria" }, "to_be_processed": "2022-09-11T12:03:46.000Z", "payment": { "shipping_fee": 630, "currency": "NGN" }, "package_status": [{ "status": "Pending", "datetime": "2022-09-11T12:03:46.000Z" }], "insurance": null, "events": [], "dropoff_station": null, "pickup_station": null, "tracking_url": "http://localhost:3000/orders/tracking/SB-6BAD4363F17C", "waybill_document": null, "date": "2022-09-11T12:03:46.000Z" } ``` {% endtab %} {% tab title="wallet.threshold.alert" %} ```json { "event": "wallet.auto_topup.succeeded", "amount": 1000, "currency": "NGN", "ref_code": "WALLET_AUTO_TOPUP_63FEF58D", "date": "2026-09-12 23:09:49" } ``` {% endtab %} {% tab title="wallet.auto\_topup.succeeded" %} ```json { "event": "wallet.auto_topup.failed", "reason": "charge_failed", //card_not_available, "failure_count": 2 //no of times charge has failed while attempting; we try 5 times } ``` {% endtab %} {% endtabs %}