Skip to main content

Register an event destination

Use webhook endpoint registration with an institution-approved HTTPS URL and event keys from the event catalog.
The creation response includes a signing secret once. Store it immediately in a secret manager with the destination, workspace, institution, and environment. Destination list responses do not return it. Never use the API key as the webhook secret.

Signature contract

Verify the exact bytes before JSON parsing or reserialization. Compare the digest in constant time. The timestamp tolerance is five minutes in either direction; keep the receiver’s clock synchronized. The following helpers implement the signature format. They validate the signature and basic envelope, but your application must still enforce destination/tenant association, durable deduplication, payload validation, and processing rules.

Receive, persist, acknowledge

  1. Apply a configured body-size limit and capture the raw bytes. Use the payload limit configured for your environment.
  2. Resolve the expected secret from the registered destination, not from an untrusted body field.
  3. Verify the signature and timestamp, then validate the event against the contract.
  4. Atomically insert the event into a durable inbox with a unique key of workspace/environment + event ID. Persist its processing job in the same transaction, or use a transactional outbox.
  5. Return 2xx after durable acceptance. A duplicate already accepted event can receive 2xx without repeating its effects.
  6. Process asynchronously. Fetch the authorized resource and apply only a newer resource version.
Do not mark an event complete before its effects are durably committed. A worker failure after acknowledgment must be recoverable from your inbox; the sender may not deliver again. An invalid signature should receive a non-2xx response and must not enter the business-processing queue.

Delivery, retries, and replay

Delivery is at least once, and arrival order is not guaranteed. Keep deduplication records for the agreed replay window, not merely the five-minute signature tolerance. The retry offsets after the first failed delivery are 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, and 24 hours. Terminal failures require delivery review and reconciliation. List retained events to discover missing IDs and delivery attempts to inspect failures. Replay preserves the original event ID. It must use a fresh delivery timestamp/signature so delayed replay can pass timestamp verification. Read configured overlap, retention and delivery timeouts from GET /v1/configuration. Authorized administrators manage URLs, subscriptions, enablement and secret rotation in the client portal; follow the webhook operations procedure. Event bodies contain resource references and limited status changes. Retrieve sensitive evidence through authenticated API reads. Do not add provider credentials, identity media, or unrestricted raw payloads to event logs.