Register an endpoint
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.
Verify a delivery
Heyrafiki sends:Heyrafiki-Event-Id: the stable event identifier;Heyrafiki-Signature:t=<unix>,v1=<hex digest>;Content-Type: application/json.
<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.
Test an endpoint
sandbox.ping. Transient failures use bounded retries and retain the same event identifier.
Accepted delivery
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.Retryable delivery
Retryable delivery
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.
Rejected delivery
Rejected delivery
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.

