Webhook endpoint and delivery problems
Diagnose invalid endpoints, signature failures, retries, disabled subscriptions, and access-loss cancellation.
Last updated
Open the subscription's delivery history and inspect the latest attempt. The status, response code or error code, endpoint, duration, and timestamps usually identify the failing layer.
Endpoint rejected
The endpoint must be public HTTPS on port 443. Quire rejects localhost, private and reserved addresses, embedded credentials, fragments, non-HTTPS schemes, and other ports. DNS is revalidated and pinned for every attempt, so a hostname that changes to a private address fails closed. Redirect responses are not followed.
Signature mismatch
Verify before parsing JSON. Compute HMAC-SHA256 over the exact X-Quire-Timestamp, a literal period, and the raw body bytes. Compare to the hexadecimal value after sha256= using a constant-time function. Confirm the receiver has the current secret, especially after rotation.
Unexpected retries
Return 2xx only when the event is durably accepted. Network errors, 408, 425, 429, and 5xx responses retry. Other 3xx and 4xx responses fail immediately. Long processing can exceed the 10-second request timeout, so queue agent work and respond first.
Canceled or missing events
A disabled or deleted subscription cancels pending attempts. Delivery also cancels when the subscription owner leaves the team or loses access to the affected collection or resource. Agent-only activity is omitted unless Include agent events is enabled; mixed human and agent update batches still deliver.
After correcting a failed endpoint or secret, use manual redelivery from the Webhooks page. The retained body and IDs make the operation safe to deduplicate.