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 makes up to eight attempts in all — the first straight away, then retries after 10 seconds, 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 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, which never changes — not on ronda-delivery-id, which stays the same across retries but is new when a delivery is replayed from the dashboard, and differs between two endpoints receiving the same event.

Endpoint requirements

• HTTPS, on a publicly resolvable address, port 80 or 443 — in test mode as in live. Ronda cannot reach localhost on your machine; to receive test webhooks while developing, expose your local server through a tunnel (ngrok, Cloudflare Tunnel) and register its https URL. (A copy of Ronda running on your own machine does allow loopback, for its own test suite — ronda.sh never does.)
• 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