Webhooks
Overview
ShipBob's webhooks can simplify your development by pushing a payload to your app whenever certain events occur. Currently, the only way to subscribe to webhooks is through our Webhooks API (more details on the API documentation page).
This API has its own scopes - webhooks_read and webhooks_write, which you must request if you are using an OAuth application. Privileged Access Tokens (PATs) will automatically be granted these scopes.
- A subscription is a request for data to be sent to a URL specified by the developer of the application. Subscriptions belong to users. An application can have multiple subscriptions for 1 user, and can have multiple subscriptions to the same topic if they are different subscription URL.
- The subscription URL is the destination to which the payload will be POSTed upon the event happening for a given topic. Subscription URLs belong to the subscription, i.e. one application can have multiple subscriptions that have different subscription URLs.
- An event is a trigger for the data for a given topic to be sent. For example - an action in the physical world like an order being shipped.
- A topic is a specific payload of data requested to be sent to the subscription URL. Applications can subscribe to multiple topics, or the same topic more than once.
- The payload is the data that is delivered.
- The response is what the ShipBob webhooks API expects to receive after making a POST request to a subscription URL. 2XX responses are expected.
Some webhooks topics are sensitive to channel - upon creating a subscription, you can specify which channel you'd like to receive data for. For example, if you have 2 sales channels creating orders but only want data sent for your Shopify channel #122233, you would pass through "shipbob_channel_id": "122233" in the header when POSTing your webhooks subscription.
Best Practices & Troubleshooting
Subscription URLs must be SSL-encrypted. We recommend RequestBin if testing in an environment without SSL.
You should not solely rely on webhooks. We recommend using GET endpoints to periodically reconcile data.
We do not allow editing of subscription URLs. Instead, you should delete the subscription, and create a new one.
Retry Policy
At this time, we do not try to re-send data if a failure occurs. Please ensure a timely 200-range response to avoid failures.
Topics
| Topic Name | Description | Scopes Required |
|---|---|---|
| order_shipped | Sends the full shipment payload when the label a shipment is purchased, printed, and placed on box for carrier pickup. While the tracking # will be available, there may be a delay while carriers scan in the package. If the order is split into multiple shipments, this will fire for each shipment. | orders_read |
Payload by Topic
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.
Please Note
- Currently Topic and SubscriptionId are not passed in our Webhook notification. In the future we will pass the Topic and SubsciptionId in the HTTP header of the webook notification, NOT in the payload. When we make that change we will update the documentation.
Example: order_shipped topic
{
"id": 111000,
"created_date": "2020-04-09T00:50:01Z",
"reference_id": "ORD-12343",
"status": "Fulfilled",
"channel": {
"id": 298339,
"name": "ShipBobs-Shopify-Store"
},
"shipping_method": "Free 2-day Shipping",
"recipient": {
"name": "John Doe",
"address": {
"address1": "100 Nowhere Blvd",
"address2": "Suite 100",
"company_name": "Wayne Enterprises",
"city": "Gotham City",
"state": "New Jersey",
"country": "USA",
"zip_code": "07093"
},
"email": "[email protected]",
"phone_number": "555-555-5555"
},
"products": [
{
"id": 10001,
"reference_id": "SKU_1209098309",
"quantity": 2,
"sku": "SKU_1209098309"
}
],
"tags": [
{
"name": "Handling instructions",
"value": "Fragile"
}
],
"shipments": [
{
"id": 1009099,
"order_id": 111000,
"reference_id": "ORD-12343",
"recipient": {
"name": "John Doe",
"address": {
"address1": "100 Nowhere Blvd",
"address2": "Suite 100",
"company_name": "Wayne Enterprises",
"city": "Gotham City",
"state": "New Jersey",
"country": "USA",
"zip_code": "07093"
},
"email": "[email protected]",
"phone_number": "555-555-5555"
},
"created_date": "2020-04-09T00:50:01Z",
"last_update_at": "2020-04-09T00:50:01Z",
"status": "None",
"status_details": [
{
"name": "string",
"description": "string",
"id": 111,
"inventory_id": 190000,
"exception_fulfillment_center_id": 0
}
],
"location": {
"id": 3,
"name": "Cicero (IL)"
},
"invoice_amount": 0,
"insurance_value": 0,
"ship_option": "Standard",
"package_material_type": "Box",
"tracking": {
"carrier": "USPS",
"tracking_number": "860C8CDC8F0B4FC7AB69AC86C20539EC",
"carrier_service": "Priority",
"tracking_url": "https://www.example.com/tracking?id=860C8CDC8F0B4FC7AB69AC86C20539EC"
},
"products": [
{
"id": 0,
"reference_id": "TShirtBlueM",
"name": "Medium Blue T-Shirt",
"sku": "TShirtBlueM",
"inventory_items": [
{
"id": 0,
"name": "Medium Blue T-Shirt",
"quantity": 0,
"lot": "22222",
"expiration_date": "2020-04-09T00:50:01Z",
"serial_numbers": [
"string"
],
"is_dangerous_goods": true
}
]
}
],
"measurements": {
"total_weight_oz": 0,
"length_in": 0,
"width_in": 0,
"depth_in": 0
},
"require_signature": true
}
]
}