Webhooks

1. 1

   Create endpoint

   In Settings → Developers → Webhooks, add your HTTPS URL and select event types.

2. 2

   Verify ownership

   Orbex Data sends a challenge request; respond with the verification token.

3. 3

   Store signing secret

   Copy the webhook signing secret to validate payload authenticity.

4. 4

   Enable in production

   Test with sandbox events before enabling for live shipment traffic.

Events are JSON documents posted to your endpoint with standard headers. The data object contains the resource snapshot at event time.

{
  "id": "evt_3Nx8kL9mP2qR",
  "type": "milestone.recorded",
  "created_at": "2026-01-15T09:41:22Z",
  "api_version": "2026-01-01",
  "data": {
    "shipment_id": "shp_7Kx9mN2pQ8vR",
    "milestone": {
      "code": "arrived_pod",
      "occurred_at": "2026-01-15T09:38:00Z",
      "location": "USLAX",
      "source": "carrier"
    }
  }
}

# Example incoming request headers
POST /webhooks/orbex HTTP/1.1
Host: integrations.yourcompany.com
Content-Type: application/json
Orbex-Signature: t=1705314082,v1=8f4e2a9b...
Orbex-Event-Id: evt_3Nx8kL9mP2qR
Orbex-Event-Type: milestone.recorded

Verify every webhook with the signing secret to prevent spoofed requests. The Orbex-Signature header contains a timestamp and HMAC-SHA256 signature of the raw request body.

import crypto from "crypto";

function verifyOrbexWebhook(payload, signatureHeader, secret) {
  const [timestampPart, signaturePart] = signatureHeader.split(",");
  const timestamp = timestampPart.replace("t=", "");
  const signature = signaturePart.replace("v1=", "");

  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Failed deliveries retry with exponential backoff over 72 hours. Return HTTP 2xx quickly—process asynchronously if your handler is slow. Persistent failures appear in the webhook dead letter queue for manual replay.

• Respond within 10 seconds to avoid timeout retries
• Return 2xx only after persisting the event id
• Use dead letter replay after fixing endpoint issues