Webhooks
Receive a signed callback when a case is created, changes status, takes a payment or closes — instead of polling the Partner API.
Last updated
RobinReturn pushes a signed HTTPS callback to your endpoint when a case changes, so you do not have
to poll GET /api/v1/cases/{id} to notice.
Register an endpoint
Endpoints are managed by an owner in the RobinReturn dashboard, under Settings → Developer — not through the Partner API. Your company also needs Partner API access to have been approved; until it is, the registration form rejects the request.
- Up to 20 endpoints per company.
- The URL must be
https://and resolve to a public host. This is checked when you register and again at delivery time, so an endpoint that later resolves to an internal address stops receiving. - A signing secret is generated per endpoint and shown once, at registration. Store it then — it is encrypted at rest and never displayed again. If you lose it, delete the endpoint and register a new one.
- An endpoint receives nothing until you subscribe it to specific events. There is no subscribe-to-everything default.
Events
Four events exist. The set is closed — no other event name is ever sent.
| Event | Fires when | data fields |
|---|---|---|
case.created | A case is created, including via the Partner API | caseId, reference |
case.status_changed | A case status transition commits | caseId, reference, from, to |
case.payment_received | A payment is recorded, partial or final | caseId, reference, amount, settled |
case.closed | A case enters a terminal state for the first time | caseId, reference, status |
Two behaviours worth building for:
- A payment that settles a case produces three callbacks, not one:
case.payment_received, thencase.status_changedtoSETTLED, thencase.closed. case.closedfires once. A later terminal-to-terminal move —SETTLEDtoCLOSED_WON, say — emitscase.status_changedbut not a secondcase.closed.
Payload
Every delivery has the same envelope:
{
"event": "case.status_changed",
"occurredAt": "2026-08-21T09:14:02.117Z",
"data": {
"caseId": "c1a2b3c4-...",
"reference": "RR-2026-000123",
"from": "LBA_SENT",
"to": "CLAIM_FILED"
}
}occurredAt is when the event happened, not when the delivery was sent. On a retry it keeps the
original value, so it is safe to use for ordering and never moves.
Verify the signature
Every delivery carries an X-RobinReturn-Signature header:
X-RobinReturn-Signature: t=1787296442,v1=5f2b8c...9e1at is a Unix timestamp in seconds and v1 is a hex HMAC-SHA256 of `${t}.${rawBody}`, keyed
with your endpoint's signing secret.
Sign over the raw request body, byte for byte. Parsing the JSON and re-serialising it changes the bytes and the signature will not match.
import crypto from "node:crypto";
function verify(rawBody, header, secret, toleranceSeconds = 300) {
// Some gateways hand headers back as an array (API Gateway multiValueHeaders,
// various proxy shims). Take the last value, and never throw on a missing one.
const raw = Array.isArray(header) ? header[header.length - 1] : header;
if (typeof raw !== "string" || typeof secret !== "string" || !secret) return false;
const parts = Object.fromEntries(
raw.split(",").map((kv) => kv.split("=").map((s) => s.trim())),
);
const timestamp = Number(parts.t);
if (!Number.isFinite(timestamp) || !parts.v1) return false;
// Reject a stale or future-dated delivery before comparing.
if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`, "utf8")
.digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(parts.v1, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}Compare in constant time, as above — a plain === on the hex string leaks timing information.
Return false on every failure rather than throwing. A verifier that throws on one failure mode and
returns false on another is an oracle: the difference tells an attacker which part of a forged
header was wrong. The verifier RobinReturn ships takes the same approach.
Reject anything whose timestamp is more than 300 seconds away from your clock. That is the tolerance RobinReturn signs against, and it is what stops a captured delivery being replayed at you later.
Delivery and retries
- A failed delivery is retried up to 5 times, with exponential back-off — so a returning
5xxendpoint sees the initial attempt plus 5 retries, 6 POSTs at most. - Each attempt times out after 10 seconds. Return a
2xxquickly and do the work afterwards; a slow handler is indistinguishable from a failing one. - Once the retries are exhausted the delivery is marked failed and stops. There is no manual replay,
so reconcile with
GET /api/v1/cases/{id}if your endpoint has been down.
Some failures are never retried
The retry budget only covers a delivery that was actually attempted. Three conditions are treated as permanent, and they produce no POST at all and no retries:
- Your hostname does not resolve, or resolves to a private or reserved address. The host is re-checked immediately before every POST, not just at registration — so a DNS outage on your side, or an endpoint later repointed inside a private network, is refused outright rather than retried.
- The endpoint is paused or deleted when the delivery comes to be sent.
- The signing secret cannot be read.
This matters if you are sizing on-call around the retry budget: the most likely failure on your side —
a brief DNS or resolution problem — is the one that gets no retries. Reconcile with
GET /api/v1/cases/{id} after any endpoint or DNS incident rather than
waiting for a redelivery that will not come.
Build your handler to be idempotent. A retry re-sends the same payload, and deliveries can arrive out of
order — treat occurredAt as the ordering signal rather than arrival time.
Webhook delivery is best-effort and never blocks the action that triggered it. A case transition, a payment or a case creation always commits whether or not the callback reaches you, so a webhook is a notification of something that already happened — never a step in the flow you can hold up.