Webhooks

Ronda POSTs a signed JSON payload to your endpoint every time something happens. Deliveries are written to an outbox in the same database transaction as the change that caused them, so an event can never be lost because a request failed.

The payload

{
  "id": "evt_9f3a2c…",
  "object": "event",
  "type": "payment.succeeded",
  "mode": "live",
  "created": 1786998900,
  "data": {
    "object": {
      "id": "pay_a348cb…",
      "object": "payment",
      "amount": 12900,
      "currency": "AMD",
      "status": "succeeded",
      "customer": "cus_1b4c…",
      "subscription": "sub_5c1e…",
      "attempt": 1,
      "is_recovery": false
    }
  }
}

Headers

Verifying a signature

The timestamp is inside the signed material, which is what makes replay detection possible: a captured request cannot be re-sent later, because its t falls outside your tolerance and changing t invalidates the HMAC. Reject anything older than five minutes.

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

export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map(kv => kv.split("=")));
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t));
  if (!Number.isFinite(Number(parts.t)) || age > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Verify against the raw request body. Parsing and re-serialising the JSON changes the bytes and the signature will not match.

Retries

Any response outside 2xx is a failure. Ronda retries up to eight times with backoff — 10 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours — then stops. An endpoint that fails twenty times in a row is disabled and shown as such in the dashboard, where you can also inspect and replay any delivery.

Reply quickly and do the work afterwards. If your handler takes longer than 8 seconds, Ronda treats the delivery as failed and will send it again.

Idempotency on your side

A retry means your endpoint can see the same event twice. Deduplicate on the event id (stable across retries) rather than ronda-delivery-id (which changes per attempt).

Endpoint requirements

• HTTPS, on a publicly resolvable address.
• Private, loopback, link-local and cloud-metadata ranges are refused — both when you save the URL and again immediately before every delivery, so DNS cannot be re-pointed at an internal service afterwards.
• Redirects are not followed.

Event catalogue