Webhooks

Webhooks allow Cargado to send real-time notifications to your application when events occur in your account. These notifications are sent as JSON payloads over HTTPS, enabling you to automate workflows and keep your systems in sync.

​

Getting Started

1. Choose Your Events
   • Review the Event Types documentation
   • Select which events you want to monitor
2. Register Your Webhook
   • Use the UI in the Cargado webhooks integration settings: Production or Sandbox
   • Or integrate programmatically via our API
   • Add your endpoint URL where you’ll receive notifications
3. Create Your Endpoint
   • Set up a public HTTPS POST endpoint
   • Verify the signature on each request (see below) to confirm it came from Cargado
   • Test locally using a tunnel such as ngrok
   • Deploy to production once tested

​

Verifying deliveries

Every webhook is signed, so you can confirm a request genuinely came from Cargado before acting on it. When you register an endpoint, Cargado returns a signing secret — store it securely; it’s only shown once. Each delivery includes three headers:

• webhook-id — a unique id for the delivery (also useful for idempotency)
• webhook-timestamp — when the delivery was signed
• webhook-signature — an HMAC over the id, timestamp, and the raw request body

Deliveries follow the Standard Webhooks specification, so the simplest way to verify one is a Standard Webhooks library for your language — it handles the signed-string construction, the encoding, and the constant-time comparison for you. If you’d rather implement it yourself, the specification defines the exact signed string, hash algorithm, signature encoding, and the header format (which may carry a version prefix and more than one signature). Two things to get right either way:

• Reject deliveries whose webhook-timestamp falls outside a tolerance window of a few minutes, to guard against replay.
• Verify against the raw request body. Parsing and re-serializing the JSON first will change the bytes and break the signature.