Delivery webhooks — payloads, signatures & retries

The platform sends outbound webhooks to your configured endpoint when relevant events happen on a service you're integrated with (e.g. a delivery status change, or a syndicated order settling).

Payload envelope

Every webhook shares the same envelope, regardless of service:

{
  "service": "delivery",
  "event": "order.in_transit",
  "version": 1,
  "data": {
    "...": "event-specific payload"
  }
}

Delivery events

Typical delivery events:

• order.created, order.accepted, order.rejected
• order.picked_up, order.in_transit, order.delivered
• order.cancelled, order.rescheduled, order.returned
• order.updated (fallback for changes not covered above)

Headers

Sent on each webhook request:

• Content-Type: application/json
• X-Webhook-Signature — HMAC-SHA256 (hex) over the raw JSON payload string, using your app's webhook secret (configurable header name in Partner Hub)
• X-Webhook-Timestamp — ISO timestamp of dispatch

Verifying the signature (Node.js)

import crypto from "crypto";

function verifyWebhook(rawBody: string, signature: string, secret: string): boolean {
  const expected = crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
  const left = Buffer.from(expected, "utf8");
  const right = Buffer.from(signature || "", "utf8");
  return left.length === right.length && crypto.timingSafeEqual(left, right);
}

Always verify against the raw request body — verifying the parsed/re-serialized JSON will produce a different signature and fail.

Delivery guarantees

• Each webhook job is deduplicated by an internal dedupe key, so the same event is not enqueued twice.
• Jobs retry on failure (network error, timeout, or non-2xx response) up to 5 attempts, with increasing backoff between attempts.
• If all attempts fail, the job is marked dead and stops retrying — treat sustained webhook failures as an incident, not a one-off.

Receiver best practices

• Return 2xx quickly; do slow processing asynchronously after acknowledging receipt.
• Verify the signature on the raw body before trusting the payload.
• Log event, service, and the verification result for every request you receive.
• Alert on sustained non-2xx responses from your own endpoint.
• Rotate your webhook secret in Partner Hub if you suspect it's been exposed.