Skip to content
RobinReturn (opens in a new tab)
Partner API

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.

EventFires whendata fields
case.createdA case is created, including via the Partner APIcaseId, reference
case.status_changedA case status transition commitscaseId, reference, from, to
case.payment_receivedA payment is recorded, partial or finalcaseId, reference, amount, settled
case.closedA case enters a terminal state for the first timecaseId, reference, status

Two behaviours worth building for:

  • A payment that settles a case produces three callbacks, not one: case.payment_received, then case.status_changed to SETTLED, then case.closed.
  • case.closed fires once. A later terminal-to-terminal move — SETTLED to CLOSED_WON, say — emits case.status_changed but not a second case.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...9e1a

t 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 5xx endpoint sees the initial attempt plus 5 retries, 6 POSTs at most.
  • Each attempt times out after 10 seconds. Return a 2xx quickly 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.