Skip to main content
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 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. 
{
  "id": 15949208,
  "created_date": "2024-04-08T10:25:53.9009945+00:00",
  "purchase_date": "2024-04-08T10:25:53.9009945+00:00",
  "reference_id": "ORD-12348",
  "order_number": "ORD-12348",
  "status": "Processing",
  "type": "DTC",
  "channel": {
    "id": 55176,
    "name": "Privileged Access Token Thursday, February 9, 2023"
  },
  "shipping_method": "Standard",
  "recipient": {
    "name": "John Doe co Wayne Enterprises",
    "address": {
      "address1": "123 Main St",
      "address2": "Suite 100",
      "company_name": "Wayne Enterprises",
      "city": "Anytown",
      "state": "NY",
      "country": "US",
      "zip_code": "12345"
    },
    "email": "[email protected]",
    "phone_number": "123-456-7890"
  },
  "products": [
    {
   "id": 4725516,
      "reference_id": "TShirtBlueM",
      "quantity": 4,
      "quantity_unit_of_measure_code": "EA",
      "sku": "TShirtBlueM",
      "gtin": "string",
      "upc": "string",
      "unit_price": 0.1,
      "external_line_id": 0
    }
  ],
  "tags": [
    {
      "name": "Handling instructions",
      "value": "Fragile"
    }
  ],
  "shipments": [
    {
      "id": 101199713,
      "order_id": 15949208,
      "reference_id": "ORD-12348",
      "recipient": {
        "name": "John Doe co Wayne Enterprises",
        "full_name": "John Doe",
        "address": {
          "address1": "123 Main St",
          "address2": "Suite 100",
          "company_name": "Wayne Enterprises",
          "city": "Anytown",
          "state": "NY",
          "country": "US",
          "zip_code": "12345"
        },
        "email": "[email protected]",
        "phone_number": "123-456-7890"
      },
      "created_date": "2024-04-08T11:13:56.9924495+00:00",
      "last_update_at": "2024-04-08T11:17:07.122+00:00",
      "last_tracking_update_at": "2024-04-08T15:17:05+00:00",
      "status": "LabeledCreated",
      "status_details": [],
      "location": {
        "id": 10,
        "name": "Moreno Valley (CA)"
      },
      "invoice_amount": 6.41,
      "invoice_currency_code": "USD",
      "insurance_value": null,
      "ship_option": "Ground",
      "package_material_type": "Box",
      "tracking": {
        "carrier": "OSMWorldwide",
        "tracking_number": "9261290306529427911297",
        "carrier_service": "ParcelSelect",
        "tracking_url": "https://tools.usps.com/go/TrackConfirmAction!input.action?tRef=qt&tLc=0&tLabels=9261290306529427911297",
        "bol": "string",
        "shipping_date": null,
        "pro_number": "string",
        "scac": "string"
      },
      "products": [
        {
          "id": 4725516,
          "reference_id": "TShirtBlueM",
          "name": "Medium Blue T-Shirt",
          "sku": "TShirtBlueM",
          "inventory_items": [
            {
              "id": 5264253,
              "name": "Medium Blue T-Shirt",
              "quantity": 4,
              "quantity_committed": 4,
              "lot": "22222",
              "expiration_date": "2024-08-24T14:15:22Z",
              "serial_numbers": [],
              "is_dangerous_goods": true
            }
          ]
        }
      ],
      "parent_cartons": [],
		"measurements": {
		  "total_weight_oz": 5,
		  "length_in": 6,
		  "width_in": 5,
		  "depth_in": 4
		},
      "require_signature": false,
      "estimated_fulfillment_date": "2024-04-09T06:59:59+00:00",
      "actual_fulfillment_date": "2024-04-08T11:17:07.122+00:00",
      "estimated_fulfillment_date_status": "FulfilledOnTime",
      "is_tracking_uploaded": false,
      "gift_message": "test message",
      "delivery_date": null
    }
  ],
  "gift_message": null,
  "shipping_terms": {
    "carrier_type": null,
    "payment_term": null
  },
  "retailer_program_data": {
    "purchase_order_number": null,
    "retailer_program_type": null,
    "mark_for_store": null,
    "department": null,
    "delivery_date": null,
    "addresses": [],
    "customer_ticket_number": null,
    "ship_by_date": null,
    "do_not_ship_before_date": null
  },
  "financials": {
    "total_price": 5.85
  }
}

{
  "id": 101199464,
  "order_id": 15948959,
  "reference_id": "ORD-12347",
  "recipient": {
    "name": "John Doe co Wayne Enterprises",
    "full_name": "John Doe",
    "address": {
      "address1": "123 Main St",
      "address2": "Suite 100",
      "company_name": "Wayne Enterprises",
      "city": "Anytown",
      "state": "NY",
      "country": "US",
      "zip_code": "12345"
    },
    "email": "[email protected]",
    "phone_number": "123-456-7890"
  },
  "created_date": "2024-04-08T10:04:44.4414562+00:00",
  "last_update_at": "2024-04-08T12:11:18.0516082+00:00",
  "last_tracking_update_at": null,
  "status": "Completed",
  "status_details": [
    {
      "name": "Delivered",
      "description": "Shipment Delivered",
      "id": 203,
      "inventory_id": null,
      "exception_fulfillment_center_id": null,
      "extra_information": null
    }
  ],
  "location": {
    "id": 10,
    "name": "Moreno Valley (CA)"
  },
  "invoice_amount": 6.41,
  "invoice_currency_code": "USD",
  "insurance_value": null,
  "ship_option": "Ground",
  "package_material_type": "Box",
  "tracking": {
    "carrier": "OSMWorldwide",
    "tracking_number": "9261290306529427911297",
    "carrier_service": "ParcelSelect",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction!input.action?tRef=qt&tLc=0&tLabels=9261290306529427911297",
    "bol": null,
    "shipping_date": null,
    "pro_number": null,
    "scac": null
  },
  "products": [
	{
	  "id": 4725516,
	  "reference_id": "TShirtBlueM",
	  "name": "Medium Blue T-Shirt",
	  "sku": "TShirtBlueM",
	  "inventory_items": [
		{
		  "id": 5264253,
		  "name": "Medium Blue T-Shirt",
		  "quantity": 4,
		  "quantity_committed": 4,
		  "lot": "22222",
		  "expiration_date": "2024-08-24T14:15:22Z",
		  "serial_numbers": [],
		  "is_dangerous_goods": false
		}
	  ]
	}
  ],
  "parent_cartons": [],
  "measurements": {
    "total_weight_oz": 5,
    "length_in": 6,
    "width_in": 5,
    "depth_in": 4
  },
  "require_signature": false,
  "estimated_fulfillment_date": "2024-04-09T06:59:59+00:00",
  "actual_fulfillment_date": "2024-04-08T12:11:18.0516082+00:00",
  "estimated_fulfillment_date_status": "FulfilledOnTime",
  "is_tracking_uploaded": false,
  "gift_message": "test message",
  "delivery_date": null
}

{
  "id": 101198202,
  "order_id": 15947699,
  "reference_id": "ORD-1234",
  "recipient": {
    "name": "John Doe",
    "full_name": "John Doe",
    "address": {
      "address1": "123 Main St",
      "address2": "Suite 100",
      "company_name": "Wayne Enterprises",
      "city": "Anytown",
      "state": "NY",
      "country": "US",
      "zip_code": "12345"
    },
    "email": "[email protected]",
    "phone_number": "123-456-7890"
  },
  "created_date": "2024-04-08T05:50:26.9451275+00:00",
  "last_update_at": null,
  "last_tracking_update_at": null,
  "status": "OnHold",
  "status_details": [
    {
      "name": "PackagePreferenceNotSet",
      "description": "No Package Preference Set For Inventory",
      "id": 407,
      "inventory_id": 4309409,
      "exception_fulfillment_center_id": null,
      "extra_information": null
    }
  ],
  "location": {
    "id": 17,
    "name": "Grapevine 2 (TX)"
  },
  "invoice_amount": 0,
  "invoice_currency_code": "USD",
  "insurance_value": 0,
  "ship_option": "Ground",
  "package_material_type": "Box",
  "tracking": null,
  "products": [
    {
      "id": 4725516,
      "reference_id": "TShirtBlueM",
      "name": "Medium Blue T-Shirt",
      "sku": "TShirtBlueM",
      "inventory_items": [
        {
          "id": 5264253,
          "name": "Medium Blue T-Shirt",
          "quantity": 1,
          "quantity_committed": 0,
          "lot": "22222",
          "expiration_date": "2019-08-24T14:15:22Z",
          "serial_numbers": [],
          "is_dangerous_goods": false
        }
      ]
    }
  ],
  "parent_cartons": [],
  "measurements": {
    "total_weight_oz": 5,
    "length_in": 6,
    "width_in": 5,
    "depth_in": 4
  },
  "require_signature": false,
  "estimated_fulfillment_date": null,
  "actual_fulfillment_date": null,
  "estimated_fulfillment_date_status": "AwaitingReset",
  "is_tracking_uploaded": false,
  "gift_message": "test message",
  "delivery_date": null
}

{
  "id": 101198202,
  "order_id": 15947699,
  "reference_id": "ORD-1234",
  "recipient": {
    "name": "John Doe",
    "full_name": "John Doe",
    "address": {
      "address1": "123 Main St",
      "address2": "Suite 100",
      "company_name": "Wayne Enterprises",
      "city": "Anytown",
      "state": "NY",
      "country": "US",
      "zip_code": "12345"
    },
    "email": "[email protected]",
    "phone_number": "123-456-7890"
  },
  "created_date": "2024-04-08T05:50:26.9451275+00:00",
  "last_update_at": null,
  "last_tracking_update_at": null,
  "status": "Exception",
  "status_details": [
    {
      "name": "OutOfStock",
      "description": "No Stock On Hand For Sku",
      "id": 303,
      "inventory_id": 5264253,
      "exception_fulfillment_center_id": 17,
      "extra_information": null
    }
  ],
  "location": {
    "id": 17,
    "name": "Grapevine 2 (TX)"
  },
  "invoice_amount": 0,
  "invoice_currency_code": "USD",
  "insurance_value": 0,
  "ship_option": "Ground",
  "package_material_type": "Box",
  "tracking": null,
  "products": [
    {
      "id": 4725516,
      "reference_id": "TShirtBlueM",
      "name": "Medium Blue T-Shirt",
      "sku": "TShirtBlueM",
      "inventory_items": [
        {
          "id": 5264253,
          "name": "Medium Blue T-Shirt",
          "quantity": 1,
          "quantity_committed": 0,
          "lot": "22222",
          "expiration_date": "2019-08-24T14:15:22Z",
          "serial_numbers": [],
          "is_dangerous_goods": false
        }
      ]
    }
  ],
  "parent_cartons": [],
  "measurements": {
    "total_weight_oz": 5,
    "length_in": 6,
    "width_in": 5,
    "depth_in": 4
  },
  "require_signature": false,
  "estimated_fulfillment_date": null,
  "actual_fulfillment_date": null,
  "estimated_fulfillment_date_status": "AwaitingReset",
  "is_tracking_uploaded": false,
  "gift_message": "test message",
  "delivery_date": null
}

{
  "id": 101198202,
  "order_id": 15947699,
  "reference_id": "ORD-1234",
  "recipient": {
    "name": "John Doe",
    "full_name": "John Doe",
    "address": {
      "address1": "123 Main St",
      "address2": "Suite 100",
      "company_name": "Wayne Enterprises",
      "city": "Anytown",
      "state": "NY",
      "country": "US",
      "zip_code": "12345"
    },
    "email": "[email protected]",
    "phone_number": "123-456-7890"
  },
  "created_date": "2024-04-08T05:50:26.9451275+00:00",
  "last_update_at": null,
  "last_tracking_update_at": null,
  "status": "Cancelled",
  "status_details": [],
  "location": {
    "id": 17,
    "name": "Grapevine 2 (TX)"
  },
  "invoice_amount": 0,
  "invoice_currency_code": "USD",
  "insurance_value": 0,
  "ship_option": "Ground",
  "package_material_type": "Box",
  "tracking": null,
  "products": [
  {
	  "id": 4725516,
	  "reference_id": "TShirtBlueM",
	  "name": "Medium Blue T-Shirt",
	  "sku": "TShirtBlueM",
	  "inventory_items": [
		{
		  "id": 5264253,
		  "name": "Medium Blue T-Shirt",
		  "quantity": 4,
		  "quantity_committed": 0,
		  "lot": "22222",
		  "expiration_date": "2024-08-24T14:15:22Z",
		  "serial_numbers": [],
		  "is_dangerous_goods": true
		}
	  ]
	}
  ],
  "parent_cartons": [],
  "measurements": {
    "total_weight_oz": 6,
    "length_in": 6,
    "width_in": 5,
    "depth_in": 4
  },
  "require_signature": false,
  "estimated_fulfillment_date": null,
  "actual_fulfillment_date": null,
  "estimated_fulfillment_date_status": "Unavailable",
  "is_tracking_uploaded": false,
  "gift_message": "test message",
  "delivery_date": null
}

​
Retry Schedule

Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt: 
  • Immediately 
  • 5 seconds 
  • 5 minutes 
  • 30 minutes 
  • 2 hours 
  • 5 hours 
  • 10 hours 
  • 10 hours (in addition to the previous) 
If an endpoint is removed or disabled delivery attempts to the endpoint will be disabled as well.  For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.  Indicating successful delivery  The way to indicate that a webhook has been processed is by returning a 2xx (status code 200-299) response to the webhook message within a reasonable time-frame (15s). Any other status code, including 3xx redirects are treated as failures.  Failed delivery handling  After the conclusion of the above attempts the message will be marked as Failed for this endpoint, and the webhook sender’s account will get email notification for notifying them of this error.  Manual retries  You can also use the application portal to manually retry each message at any time, or automatically retry (“Recover”) all failed messages starting from a given date. Webhooks Manual Retries Pn

​
Static Source IP Addresses

In case your webhook receiving endpoint is behind a firewall or NAT, you may need to allow traffic from static IP addresses. This is the full list of IP addresses that webhooks may originate from. 
44.228.126.217
50.112.21.217
52.24.126.164
54.148.139.208
2600:1f24:64:8000::/56

​
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

  • Ensure your subscription URL is correct and publicly accessible.
  • Confirm your app returns a 2XX response to ShipBob’s POST request.
  • Verify that your app has the correct webhooks_read or webhooks_write permissions.
  • Ensure your system processes events efficiently and responds within 5 seconds.
  • Return a 2XX response before doing heavy processing.
  • Use timestamps from the payload to sort events properly.
  • Handle events individually, rather than relying on strict order.
  • Webhooks are not guaranteed to be sent only once.
  • Implement idempotency checks: Store received event IDs and ignore duplicates.