Webhooks

Instead of fetching updates for tracking and batch label creation manually, you can use Shippo webhooks to get notified when statuses change.

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:

  • 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.

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 5 times with a 10 second delay between each try. Thus each webhook will receive, at most, 6 messages within 1 minute.