Webhook Events

Subscribe to events instead of polling. Webhook endpoints are managed in the dashboard (Developers, Webhooks); there is no public API for creating them. Add a URL, choose your events, copy the signing secret, and Duro delivers signed, retried POSTs for the whole subscription lifecycle to your server. The transport mechanics are in the webhooks chapter; this page is the shared envelope reference, and the per-event payloads are split by category in the left sidebar. The catalog is defined once as DuroEvent in @duro/billing (packages/billing/src/events.ts) and served live at GET /v1/events/types. Every payload is assembled by WebhookPayload.build (packages/merchant-api/src/webhooks/payload.ts); the samples on each page match that builder field for field.

Events by category

Subscription events

State-machine transitions: created, activated, updated, plan changed, paused/resumed, past due, recovered, unpaid, cancelled, expired, incomplete expired.

Payment & invoice events

Charge and invoice outcomes: invoice created, payment success, failed, recovered, refunded, and action required.

Checkout events

Hosted and inline checkout session outcomes: completed, failed, and cancelled.

Payout & bill events

Money-out and VAS outcomes: payout initiated, completed, failed, and bill payment completed.

The delivery envelope

Every delivery is a POST with this body:

{
  "id": "evt_01hkbz4pq9z3k7t8v9x2y1b5c6",
  "type": "subscription_payment_success",
  "createdAt": "2026-06-28T09:00:00.000Z",
  "data": { }
}

Field	Type	Notes
`id`	string	The event id (`evt_` prefix). Dedupe on this.
`type`	string	One of the event names in the category pages.
`createdAt`	string	ISO-8601 timestamp of the event.
`data`	object	Event-specific, with related resources expanded inline.

Related resources are expanded inline: whenever the raw event carries a subscriptionId, invoiceId, customerId, or planId, the builder replaces it with the full subscription, invoice, customer, or plan object (whichever apply) and drops the flat *Id field. A top-level status is also dropped once the subscription object (which already carries status) is present. Flat fields the builder does not know how to expand (for example payoutId, checkoutToken, failureCode) are passed through unchanged. The expanded objects are compact projections, always shaped like this:

{
  "id": "sub_01hkbz3m4n5p6q7r8s9t0v1w2x",
  "status": "active",
  "customerId": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
  "planId": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
  "currentPeriodStart": "2026-06-28T09:00:00.000Z",
  "currentPeriodEnd": "2027-06-28T09:00:00.000Z",
  "trialEndsAt": null
}

{
  "id": "cus_01hkbz2a1b2c3d4e5f6g7h8j9k",
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "phone": "+2348012345678"
}

{
  "id": "plan_01hkbz1z0y9x8w7v6u5t4s3r2q",
  "name": "Pro Annual",
  "amount": 500000,
  "currency": "NGN",
  "interval": "year",
  "intervalCount": 1
}

{
  "id": "inv_01hkbz4a5b6c7d8e9f0g1h2j3k",
  "amount": 500000,
  "currency": "NGN",
  "status": "paid",
  "periodStart": "2026-06-28T09:00:00.000Z",
  "periodEnd": "2027-06-28T09:00:00.000Z"
}

Amounts are integer minor units (kobo). Every sample on the category pages shows the full envelope so you can see exactly what lands on your endpoint. And these headers ride on every request:

Header	Value
`duro-signature`	`t=<unix>,v1=<hex hmac-sha256>`
`duro-event-id`	the event id (dedupe on this)
`duro-event-type`	the event type

Verifying a signature

Recompute the HMAC and compare in constant time. The signed payload is ${t}.${rawBody}; use the raw request body, not a re-serialised object. Duro signs with WebhookSigner in @duro/crypto; the default replay tolerance is 300 seconds (5 minutes).

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((kv) => {
      const i = kv.indexOf("=");
      return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
    }),
  );
  const t = Number(parts.t);
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Always verify against the raw body bytes. If your framework parses JSON before you can read the raw body, configure it to expose the raw payload (Duro does this internally with a raw-body saver for exactly this reason).

Retries & replay

A non-2xx response (or a network error) is retried on an exponential backoff: 1m, 5m, 30m, 2h, 6h, 24h, six attempts, after which the delivery is marked failed. Make your handler idempotent: dedupe on duro-event-id, because a slow 200 can still be retried. You can also replay any delivery from the dashboard’s delivery inspector.

Retrieve a payload

Have the event id (from a duro-event-id header, the dashboard, or an earlier payload) but missed or couldn’t verify the delivery? Re-fetch the exact same body any time; there is no need to store payloads yourself:

curl https://api.useduro.com/v1/events/evt_01hkbz4pq9z3k7t8v9x2y1b5c6/payload \
  -H "Authorization: Bearer $DURO_SECRET_KEY"

The data field is byte-for-byte identical to what Duro POSTed, the same enriched objects, which makes reconciliation a single call. Full reference: GET /v1/events/{id}/payload. The response also flags provenance so you know whether it was actually sent:

If the event has been delivered to at least one endpoint, you get that delivery’s stored body plus "delivered": true.
If it has not (no endpoint was subscribed, or delivery is still pending), you get a freshly-built preview plus "delivered": false, "preview": true (the exact bytes an endpoint would receive).

To inspect the per-endpoint attempt history for an event (status, response code, retry timing), use GET /v1/events/{id}/deliveries.

​Events by category

Subscription events

Payment & invoice events

Checkout events

Payout & bill events

​The delivery envelope

​Verifying a signature

​Retries & replay

​Retrieve a payload

Events by category

The delivery envelope

Verifying a signature

Retries & replay

Retrieve a payload