Webhooks tell your server about changes without making it repeatedly scan all records. The payload provides identifiers and event context. When you need participant details, retrieve the appropriate record with a separately scoped API key.
Register an HTTPS endpoint
Use create webhook with webhooks:manage. Supply a public HTTPS URL and the event names you need. Production delivery rejects private and loopback destinations, and redirects are not followed. An organization can have up to 10 active endpoints.
Save the returned signing secret in server secret storage. It is shown on creation and rotation, not returned by ordinary endpoint listing. The webhook secret verifies incoming messages; it is not an API bearer key.
Verify before processing
Read the raw request body and verify the Waiver-Signature header before parsing or trusting the JSON. The signature covers the timestamp and the exact raw bytes. Reserializing parsed JSON can change the bytes and break verification.
Apply the five-minute timestamp tolerance and compare the HMAC in constant time. The verification guide provides a Node.js implementation and the required header format.
Store the work before returning success
After verification, durably save the delivery or enqueue it in a persistent queue. Only then return a 2xx response. Acknowledging first and starting an in-memory background task can lose the event if your process crashes.
Keep receipt fast. Delivery has a 10-second timeout, so PDF downloads, external CRM calls and slow reporting jobs belong in the worker. A signed event may precede PDF readiness.
Expect retries and separate events
Use Waiver-Delivery-Id to deduplicate attempts. Do not depend on event ordering. Store the delivery state and process idempotently, then observe failures through the delivery history.
Use test webhook for a ping through the same delivery system. The test route is limited to 10 requests per minute. Review event availability before subscribing, because reserved event names do not imply emitted production events.