ShipBob webhooks automatically notify your app when key events occur, allowing you to keep your data in sync.

​
Getting Started

1

Subscribe to webhooks

Create a webhook to subscribe to an event and define a subscription URL.

2

Receive Webhook Events

When the event occurs, ShipBob sends a POST request to your subscription URL with relevant data.

3

Acknowledge Receipt

Your system should return a 2XX response to confirm successful receipt.

4

Handle Retries

If no 2XX response is received, ShipBob retries delivery for up to 24 hours using an exponential backoff strategy.

​
Key Concepts

  • Subscription: A request to receive webhook notifications at a specified URL.
  • Subscription URL: The endpoint where webhook data is sent.
  • Event: A trigger that generates webhook data (e.g., an order being shipped).
  • Topic: The category of event data being sent.
  • Payload: The actual event data sent in the webhook.
  • Response: A 2XX HTTP response is required to confirm webhook receipt.

​
Common Use Cases

  • ✅ Real-time Order Tracking - Receive order_shipped and shipment_delivered events to provide live tracking updates to customers.
  • ✅ Inventory Management - Monitor shipment_exception events to detect and respond to stock shortages.
  • ✅ Automated Customer Notifications - Trigger automated emails or SMS notifications when shipments are delayed (shipment_onhold) or delivered (shipment_delivered).
  • ✅ Order Cancellation Handling - Use shipment_cancelled events to update your system when a shipment is canceled.
  • ✅ Multi-Channel Support - Filter webhook data by sales channel to manage orders from different platforms separately.

​
Webhook Topics & Events

TopicDescriptionScopes Required
order_shippedFires when a shipping label is purchased, printed, and scanned. If the order is split into multiple shipments, this fires per shipment.orders_read
shipment_deliveredFires when a shipment is delivered to the customer.orders_read or fulfillments_read
shipment_exceptionFires when a shipment is moved to exception status (e.g., out-of-stock items).orders_read or fulfillments_read
shipment_onholdFires when a shipment moves to On-Hold status due to missing information (e.g., address issues).orders_read or fulfillments_read
shipment_cancelledFires when a shipment is canceled. Does not fire for manually canceled or imported orders.orders_read or fulfillments_read

​
Webhook Headers

ShipBob sends webhook notifications with the following headers:

{
  "shipbob-subscription-id": "1582",
  "shipbob-topic": "order_shipped",
  "content-type": "application/json; charset=utf-8"
}

​
Webhook Payloads (Example Responses)

Unless specified in the table above, the webhook notification sends the full data model of the underlying resource, that is available in the GET endpoint.

​
Best Practices

✅ Use HTTPS - Subscription URLs must support SSL. Use RequestBin for testing if needed.

✅ Implement Redundancy - Webhooks may be delayed or lost. Use 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 ids and discard duplicates to prevent redundant processing.

✅ Logging & Monitoring - Log webhook requests and responses to diagnose issues.

​
Troubleshooting Guide