Webhook reference

Available webhook destinations

Three outbound webhook surfaces ship today:

Common envelope

Every webhook delivery uses a common JSON envelope:

{
  "event_id": "evt_01HZQX...",
  "event_type": "scheduled_export.completed",
  "tenant_id": "acme-logistics",
  "timestamp": "2026-05-09T14:32:08Z",
  "delivery_attempt": 1,
  "data": { ... event-specific payload ... }
}

The event_id is unique per logical event — consume idempotently keyed on this id, since retries deliver the same id with an incremented delivery_attempt.

Signature verification

Every webhook delivery includes an X-PulseCargo-Signature header containing an HMAC-SHA256 signature computed over the request body using your tenant's webhook signing secret.

To verify in pseudocode:

signature = HMAC-SHA256(your_signing_secret, request.body)
expected  = request.headers["X-PulseCargo-Signature"]
constant_time_equal(signature, expected)  // must use constant-time compare

Reject any request where the signature does not match. The signing secret is rotatable; rotation is communicated 30 days in advance via the admin surface.

Retry policy

If your endpoint returns a non-2xx status code (or fails to respond within 10 seconds), PulseCargo retries with exponential backoff:

• Attempt 1 — immediate
• Attempt 2 — 1 minute later
• Attempt 3 — 5 minutes later
• Attempt 4 — 30 minutes later
• Attempt 5 — 2 hours later
• Attempt 6 — 12 hours later
• Attempt 7 (final) — 24 hours later

After the seventh failed attempt the event is marked permanently failed and surfaced in the tenant's webhook health dashboard. The original event_id is preserved so a manual re-send (after you fix the receiving endpoint) reconciles cleanly.

Receiver expectations

• Respond fast. Return a 2xx within 10 seconds. Process the payload asynchronously if needed.
• Idempotency. Key on event_id. Treat repeat deliveries as no-ops after the first successful processing.
• Verify signature. Reject requests without a valid signature.
• Use HTTPS. HTTP endpoints are not allowed for production webhooks.
• Allow our IP range. If your endpoint is firewalled, allow PulseCargo's outbound IP range (provided in the admin surface) to reach you.

Health monitoring

Tenant administrators can view webhook delivery health under Admin → Integrations → Webhooks: success rate per destination, last successful delivery, currently retrying events, permanently failed events with replay buttons.

Permanently failed events are retained for 90 days for replay; older failed events are purged.

Security and audit

Every outbound webhook delivery is logged in OutboundApiTraffic with timestamp, destination URL, response status, and delivery attempt. Tenant administrators can query the log for compliance evidence.

Signing-secret rotation, destination URL changes, and webhook-on/off toggles are all audit-logged. SOC 2 evidence collection.