Webhooks

Configure your webhook URL and secret in the dashboard. Entrega sends a signed POST whenever delivery state changes are enqueued.

Headers

Payload

{
  "id": "evt_12f0b71f-4d51-449b-9d42-81fdb1d2d5ee",
  "event": "delivery.in_transit",
  "occurred_at": "2026-04-29T18:10:00Z",
  "delivery_id": "f1d7a3f7-7a1f-4994-9c1f-68fe3c50a4f7",
  "delivery_reference": "DLV-2026-00042",
  "data": {
    "status": "in_transit"
  }
}

Verify the signature

The signature is an HMAC-SHA256 over the exact JSON request body using your webhook secret.

import crypto from "node:crypto"

function verifyEntregaSignature(rawBody, signature, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex")

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

Retries

Return any 2xx status to acknowledge a webhook. Non- 2xx responses and network failures are retried with exponential backoff for up to 10 attempts.

Recommended handler

1. Verify x-entrega-signature .
2. Store the webhook id for idempotency.
3. Enqueue internal processing.
4. Return 200 quickly.