Webhooks

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

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.

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

Events

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": "[email protected]",
		"phone": "010000038198",
		"tracking_code": "2232",
		"tracking_message": "Tracking code: 14815206",
		"rider_info": null
	},
	"ship_from": {
		"name": "Lebron James",
		"phone": "[phone]",
		"email": "[email protected]",
		"address": "Teslim Balogun Stadium, Alh. Masha Road, Lagos, Nigeria"
	},
	"ship_to": {
		"name": "Lebron James",
		"email": "[email protected]",
		"phone": "[phone]",
		"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.

Event	Description
shipment.label.created	When a new shipping label is created.
shipment.status.changed	When the status of your shipment changes
shipment.cancelled	When your shipment is cancelled
shipment.cod.remitted	When payment for a cash-on-delivery order has been remitted to your account