Shipbubble sends a payload to notify your application each time there is a status change on any of your labels (orders).

The payload for each webhook event will include information about the related API response. Your provided endpoint should be set up to receive a HTTP POST request, and must always return a 200 HTTP response within 15 seconds of the request if not it would be marked as failed.

We’ll send a webhook every 5 minutes for the first 5 tries in the case of a failed webhook.


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 SHA512 algorithm and SECRET_KEY as a key of the hash


Shipbubble provides various webhook events to notify you about changes in your shipment process.

	"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"

Here are some of the event types we send, the list will be updated as we release more actions in the future.

Last updated