Webhooks - Saguaro Transport

Overview

Webhooks allow you to receive real-time notifications when shipment events occur. Instead of polling our API, we’ll send HTTP POST requests to your endpoint.

Setting Up Webhooks

Log in to your Client Portal
Navigate to Settings > Webhooks
Add your endpoint URL
Select which events to receive
Save and test your webhook

Webhook Events

Event	Description
`shipment.created`	New shipment created
`shipment.dispatched`	Driver assigned
`shipment.picked_up`	Cargo picked up
`shipment.in_transit`	Shipment in transit
`shipment.delivered`	Successfully delivered
`shipment.exception`	Issue or delay occurred

Webhook Payload

{
  "event": "shipment.delivered",
  "timestamp": "2024-01-15T14:25:00Z",
  "data": {
    "tracking_number": "SGT-2024-00001",
    "status": "delivered",
    "delivered_at": "2024-01-15T14:25:00Z",
    "signed_by": "Jane Receiver"
  }
}

Verifying Webhooks

Each webhook includes a signature header for verification:

X-Saguaro-Signature: sha256=abc123...

Verify by computing HMAC-SHA256 of the payload using your webhook secret.

Retry Policy

Failed webhooks are retried:

3 attempts over 1 hour
Exponential backoff between retries
After 3 failures, webhook is disabled (you’ll be notified)