Webhooks

Instead of fetching updates for tracking, batch labels, and transactions manually, you can use Shippo webhooks to get notified when a status changes.

Setting up and testing Webhooks

You can set up webhooks on the API settings page of your Shippo Dashboard. This page also allows you to test webhooks with a sample payload.

Shippo will POST to all active webhooks connected in your Shippo account whenever the status of your Event changes.

Event attributes:

  • transaction_created: sent whenever a transaction is created in your account. The POST request body will contain a JSON of the Transaction object that was created.
  • transaction_updated: sent whenever a transaction is updated in your account. The POST request body will contain a JSON of the Transaction object that was updated.
  • track_updated: for shipment status updates. The POST request body will contain a JSON of the Transaction object (for shipments created through Shippo) or Tracking Object (for shipments created outside of Shippo).
    Shipment statuses are polled by us from the carrier API every ~2 hours, if there are any status changes, we immediately POST updates to the webhook.
  • batch_created: for creating the Batch object that contain BatchShipments. This process is done asynchronously, so first you'd get an empty Batch Object back, then BatchShipments will be created in the background.
  • batch_purchased: for purchasing BatchShipments through the Batch endpoint. This request is done asynchronously as well. Once purchases are complete, you will be able to download a merged PDF containing up to 100 labels per file.

Additionally, Shippo-API-Version is included in the header of all webhook responses to indicate what version of the API is being used.

Expected Webhook behavior

Shippo expects your webhook to return a response with a 2XX HTTP status code, indicating that the webhook has been received successfully. If Shippo doesn't receive a 2XX response status code, the webhook POST request will be re-tried 1 time with a 3 second delay between each try. Thus each webhook will receive, at most, 2 messages within 3 seconds. It is recommended that the maximum response time for your webhook be of 5 seconds or less.