Webhook delivery troubleshooting

What this guide covers

Trace webhook delivery from receipt through signature checks, queueing, idempotent processing, and response timing. Work through each step in order, preserve safe reference details, and stop before repeating an action if the original result is still unclear.

Step-by-step

1. Confirm the public HTTPS endpoint is reachable and accepts the documented method and content type.
2. Record delivery IDs, event types, timestamps, status codes, and response duration without storing secrets.
3. Verify signatures against the exact raw request bytes according to the approved integration documentation.
4. Return a timely success response after durable receipt, then perform longer business processing asynchronously.
5. Deduplicate by event or delivery ID and make handlers safe to run more than once.

Troubleshooting

• A timeout can occur even when your application eventually processes the event; inspect timing and deduplicate retries.
• A 404 or 405 usually indicates route or method configuration.
• Signature failures commonly involve the wrong environment secret or altered request body.

If the result changes after a check, record what changed and the exact time. That detail is often more useful than repeating every step.

Before contacting support

Prepare the smallest set of information needed to explain the issue. Redact passwords, one-time codes, API keys, authorization headers, CVVs, full card numbers, and full bank account details.

• Delivery ID, event type, and UTC time
• Response code and latency
• Redacted application log around the attempt

State the expected outcome, observed outcome, current impact, and whether the issue is ongoing or intermittent.