Skip to main content

Troubleshoot webhook delivery

Diagnose missed, delayed, or failing webhook deliveries and retries.

Symptom​

Your endpoint is not receiving webhook events, or events arrive late, out of order, or as repeated duplicates. You may also see events for some Broadcasts but not others, or a spike of retries after your service was briefly unavailable.

Likely causes​

  • Endpoint unreachable or slow — the receiving URL times out, returns a non-2xx status, or takes too long to respond, so the platform marks the delivery as failed and queues a retry.
  • Signature or auth rejection — your service rejects requests because the signing secret rotated, the signature header is not being verified correctly, or an added auth layer (WAF, IP allowlist, basic auth) blocks our sender.
  • Subscription scope — the webhook is not subscribed to the event type or the Folder/Broadcast you expect, so those events are never sent.
  • Duplicate handling — retries after a timeout deliver the same event more than once; without idempotency checks these look like extra events.
  • TLS or certificate issues — an expired, self-signed, or incomplete certificate chain causes the connection to fail before the payload arrives.

Fixes​

  1. Confirm the endpoint is healthy. Return a 2xx status quickly (acknowledge first, process asynchronously). Aim to respond within a few seconds so deliveries are not treated as timeouts.
  2. Verify the signature. Recompute the signature from the raw request body using your current signing secret and compare it to the header. If the secret was rotated, update it everywhere (confirm the exact header and secret location in your account).
  3. Check the subscription. Make sure the webhook is enabled and subscribed to the event types and scope you need. Send a test event and watch for it.
  4. Review the delivery log. Inspect recent attempts, response codes, and retry history to see whether events were sent and rejected versus never sent (confirm where delivery logs live in your account).
  5. De-duplicate by event ID. Store each event's unique ID and ignore repeats so retries are safe.
  6. Allow our sender. Whitelist our source addresses in any firewall, WAF, or IP allowlist, and confirm your TLS certificate chain is valid and current.

Still stuck?​

Capture the affected event IDs, timestamps, the endpoint URL, and the exact response your server returned, then contact your account support team with those details so delivery can be traced end to end.

Canonical terms: Author, Edition, Folder (Project Folder), Broadcast. See the Glossary.