Subscribe to webhooks
Receive Webhook Events
POST
request to your subscription URL with relevant data.Acknowledge Receipt
2XX
response to confirm successful receipt.Handle Retries
2XX
response is received, ShipBob retries delivery using an exponential backoff strategy.2XX
HTTP response is required to confirm webhook receipt.order.shipped
and order.shipment.delivered
events to provide live tracking updates to customers.order.shipment.exception
events to detect and respond to stock shortages.return.completed
events to update your system when a return has successfully been processed and completed by ShipBob.Topic (2025-07) | Description | Scopes Required |
---|---|---|
order.shipped | Fires when a shipping label is purchased, printed, and scanned. If the order is split into multiple shipments, this fires per shipment. | orders_read |
order.shipment.delivered | Fires when a shipment is delivered to the customer. | orders_read or fulfillments_read |
order.shipment.exception | Fires when a shipment is moved to exception status (e.g., out-of-stock items). | orders_read or fulfillments_read |
order.shipment.on_hold | Fires when a shipment moves to On-Hold status due to missing information (e.g., address issues). | orders_read or fulfillments_read |
order.shipment.cancelled | Fires when a shipment is canceled. Does not fire for manually canceled or imported orders. | orders_read or fulfillments_read |
return.created | Fires when a return is created. | returns_read |
return.updated | Fires when a return is updated. | returns_read |
return.completed | Fires when a return is completed. | returns_read |
Webhook topics for 1.0 and 2.0 versions
Topic (1.0, 2.0) | Description | Scopes Required |
---|---|---|
order_shipped | Fires when a shipping label is purchased, printed, and scanned. If the order is split into multiple shipments, this fires per shipment. | orders_read |
shipment_delivered | Fires when a shipment is delivered to the customer. | orders_read or fulfillments_read |
shipment_exception | Fires when a shipment is moved to exception status (e.g., out-of-stock items). | orders_read or fulfillments_read |
shipment_onhold | Fires when a shipment moves to On-Hold status due to missing information (e.g., address issues). | orders_read or fulfillments_read |
shipment_cancelled | Fires when a shipment is canceled. Does not fire for manually canceled or imported orders. | orders_read or fulfillments_read |
Webhook headers for 1.0 and 2.0 versions
order.shipped
or return.completed
.GET
endpoints to periodically reconcile data.
✅ Retry Handling - Events may arrive out of order due to retries—handle them as independent updates.
✅ Use Idempotency - Store webhook event id
s and discard duplicates to prevent redundant processing.
✅ Logging & Monitoring - Log webhook requests and responses to diagnose issues.
Webhook Not Triggering?
returns a 2XX response
to ShipBob’s POST
request.has the correct webhooks_read or webhooks_write permissions
.Webhook Retries Are Overloading My Server
2XX
response before doing heavy processing.Webhook Data is Out of Order
Receiving Duplicate Events?