Skip to main content

​
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

  1. Log in to your Client Portal
  2. Navigate to Settings > Webhooks
  3. Add your endpoint URL
  4. Select which events to receive
  5. Save and test your webhook

​
Webhook Events

EventDescription
shipment.createdNew shipment created
shipment.dispatchedDriver assigned
shipment.picked_upCargo picked up
shipment.in_transitShipment in transit
shipment.deliveredSuccessfully delivered
shipment.exceptionIssue 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)