Operate
Operate reliable webhooks
Design webhook consumers for at-least-once delivery, retries, deduplication, and secret rotation.
Deduplicate delivery IDs
Webhook delivery is at least once. Store X-MD2PDF-Delivery before applying side effects and make the resulting transaction idempotent.
Acknowledge after durable acceptance
Return a 2xx response only after durable acceptance. Retryable failures are attempted for up to 24 hours with bounded exponential delay.
- Avoid long work inside the request handler.
- Queue verified events for background processing.
- Treat event ordering as non-guaranteed.
Rotate without downtime
Create a new signing secret through the rotation endpoint, deploy it to consumers, confirm delivery, and then remove the superseded secret.