Webhooks

Subscribe to Heyrafiki events, verify signatures and handle retries.

Heyrafiki POSTs a JSON event to your endpoint when something happens. Respond 200 within 10 seconds.

{
  "id": "evt_5c2a9f13",
  "object": "event",
  "type": "session.settled",
  "created_at": "2026-08-04T10:52:11Z",
  "data": {
    "id": "ses_2f8b10d4",
    "object": "session",
    "state": "settled"
  }
}

Events

Type	Fires when
session.booked	A Session is created and payment is held
session.delivered	Both parties attended
session.cancelled	Either party cancels
note.approved	A Practitioner approves a Note
claim.submitted	A Claim goes to a Payer
claim.approved	A Payer approves a Claim
claim.rejected	A Payer rejects a Claim, with a reason
payout.settled	Money reaches a Practitioner
practitioner.verified	A verification check completes

Verifying signatures

Every request carries X-Heyrafiki-Signature, an HMAC-SHA256 of the raw body keyed with your webhook secret.

import crypto from "node:crypto";

export function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Compute the HMAC over the raw request body, before any JSON parsing. Re-serialised JSON produces a different signature. Always compare in constant time.

Reject anything that fails verification. Do not fall back to trusting the payload.

Retries

A non-200, a timeout or a connection failure is retried with exponential backoff for 24 hours. Delivery is at-least-once, so handlers must be idempotent: key on event.id and ignore ones you have already processed.

Order is not guaranteed. Use created_at to resolve sequence.

Handling

Acknowledge first, work after. Return 200 as soon as you have persisted the event, then process it in a queue. Work done before the response counts against the 10-second timeout.