---
title: "Debug webhook delivery and verification"
description: "Diagnose missing or failing BlindPay webhooks: endpoint config, signature mismatches, raw-body pitfalls, retries, and replay."
date: "2026-08-26"
category: "setup"
products: ["webhooks"]
---

Paste this prompt into your coding agent when webhooks are not arriving or signature verification keeps failing.

## Prompt

```text
My BlindPay webhooks are failing (not arriving, or failing signature verification). Diagnose and fix the problem.

Before debugging, read these sources and follow them over any prior knowledge:
- https://blindpay.com/docs/llms.txt (read the webhooks, webhook verification, and webhook events pages)

Work through this checklist against my code and configuration, in order:
1. Endpoint registration: list my webhook endpoints (GET /v1/instances/{instance_id}/webhook-endpoints). Confirm the URL is https, publicly reachable, and that the events array actually includes the events I expect (an empty array means all events; a non-empty array silently excludes everything else).
2. Secret mismatch: confirm the whsec_ secret in my config was fetched for this exact endpoint ID via GET /v1/instances/{instance_id}/webhook-endpoints/{endpoint_id}/secret. Each endpoint has its own secret; a secret from another endpoint or instance verifies nothing.
3. Raw body: verify my handler computes the HMAC over the exact raw request bytes. Framework body parsers that deserialize and re-serialize JSON (reordered keys, changed whitespace, unicode escaping) are the most common cause of signature failures. Read the raw body before any JSON middleware touches it.
4. Signed content and comparison: the signed content must be "{svix-id}.{svix-timestamp}.{raw body}", the key is the base64-decoded portion of the secret after the whsec_ prefix, the digest is base64, and svix-signature contains space-delimited candidates like "v1,<sig>"; strip the version prefix and compare each candidate in constant time. Check the timestamp tolerance (reject only beyond 5 minutes) and my server's clock skew.
5. Response behavior: my handler must return 2xx quickly. Check for slow synchronous processing causing timeouts (which look like failures and trigger retries) and confirm I dedupe on svix-id since retries reuse it.
6. Reproduce and verify the fix: build a local test that signs a fixture payload with a known secret and asserts my middleware accepts it, plus a tampered variant it must reject. Then replay a real event from the BlindPay dashboard's Events view to confirm end to end.

Deliverables: the specific root cause found, the fix, and the signature verification unit tests so this class of bug cannot silently return.
```

## How to use

1. Paste the prompt and give the agent access to your webhook handler code and (redacted) config.
2. Have a real failing request's headers handy if you captured them; they speed up diagnosis.
3. Use the dashboard's event replay to confirm the fix without creating new payments.

## Related docs

- [Webhooks](https://blindpay.com/docs/learn/webhooks)
- [Signature verification](https://blindpay.com/docs/learn/webhooks-verification)
- [Event catalog](https://blindpay.com/docs/learn/webhooks-events)