Skip to main content

Register an endpoint

The response contains signing_secret once. Store it in a secret manager. Webhook endpoints use HTTPS on an approved public hostname. Redirects and private network addresses are refused.
Return 2xx after signature verification and durable event capture. Run slow Claim, reporting or notification work asynchronously.

Verify a delivery

Heyrafiki sends:
  • Heyrafiki-Event-Id: the stable event identifier;
  • Heyrafiki-Signature: t=<unix>,v1=<hex digest>;
  • Content-Type: application/json.
Compute HMAC-SHA256 over <timestamp>.<raw body> with the signing secret. Compare signatures in constant time and reject timestamps outside five minutes. Verify the raw bytes before parsing JSON.
Read and verify the raw request body. Re-serializing parsed JSON changes the signed bytes and invalidates the comparison.

Test an endpoint

The sandbox sends sandbox.ping. Transient failures use bounded retries and retain the same event identifier.

Accepted delivery

Return 200, 202 or another 2xx response only after the event identifier and raw payload are durably captured. Duplicate identifiers return success without repeating the business action.
A timeout or retryable server response keeps the same event identifier. Consumers must make event processing idempotent and must not create a second Claim, payment action or notification.
Reject a missing signature, invalid digest or stale timestamp before parsing or processing the event. Do not reveal the signing secret or comparison details in the response.

Event types

Claim Events contain public workflow identifiers and state. They do not contain Person, Member or clinical content.
Last modified on August 14, 2026