Webhooks: signing, retries, events

Register an HTTPS endpoint with POST /v1/webhooks (scope webhooks.manage). Each event is also gated by its own scope, checked when it is queued and again at delivery, so removing a scope or revoking the client stops it.

Payload

No health data, ever: event, id (the same for every endpoint the event fans out to), created_at, resource_url (a /v1 path to GET with your token, where the data is consent-filtered and audited as a read) and, on events about one member, member_ref.

Signing

Webhooks are signed: Norvya-Signature: t=<unix>, v1=<HMAC-SHA256(secret, "t." + body)>. Each delivery also carries Norvya-Event and Norvya-Delivery. The secret is shown once, at registration.

• Recompute the HMAC over the raw body bytes and compare in constant time.
• Reject timestamps more than 5 minutes off.
• De-duplicate on Norvya-Delivery: delivery is at least once. A retried delivery is re-signed with a fresh t.

Delivery and retries

• Endpoints must be https; private, loopback and link-local addresses are refused at registration and on every send.
• Anything other than a 2xx (redirects included: they are never followed) is a failed attempt, retried after 1 minute(s) × 2^{attempt − 1}, capped at 6 hours, up to 8 attempts. An endpoint that keeps failing is disabled; re-enable it with POST /v1/webhooks/{id}/enable.

Events

The full catalogue, with each event's scope and family, is on the Events reference page. In the spec, events are in the OpenAPI webhooks section.

• GET/v1/webhooksYour webhook endpoints
• POST/v1/webhooksRegister a webhook endpoint (secret shown once)
• DELETE/v1/webhooks/{webhook_id}Delete a webhook endpoint
• POST/v1/webhooks/{webhook_id}/enableRe-enable a disabled webhook endpoint
• GET/v1/webhooks/{webhook_id}/deliveriesRecent deliveries of one webhook endpoint