Skip to content
Back to Prompts

Debug webhook delivery and verification

Diagnose missing or failing BlindPay webhooks: endpoint config, signature mismatches, raw-body pitfalls, retries, and replay.

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.

One API.
Multiple payment rails.

Blind Pay, Inc. (“BlindPay”) is a United States-based financial technology and payments infrastructure company, incorporated in the State of Delaware on May 2, 2024. BlindPay is duly registered as a Money Services Business (“MSB”) with the Financial Crimes Enforcement Network (“FinCEN”) under registration number 31000277566153. BlindPay is not a state-licensed money transmitter and does not, in its own capacity, engage in regulated money transmission services. All such regulated activities are conducted exclusively through, and under the licenses of, duly authorized financial institution partners. BlindPay's role is limited to providing financial technology, virtual account management, payment processing, and related payments infrastructure services that facilitate payment flows and account functionalities. These services are provided in coordination with its licensed partners and in compliance with applicable federal MSB requirements and relevant state regulatory frameworks.

Blind Pay, LLC (“BlindPay”) is a Delaware limited liability company formed on June 24, 2025. BlindPay is duly registered as a Money Services Business (“MSB”) with the Financial Crimes Enforcement Network (“FinCEN”) under registration number 31000318334247 and is listed in the Nationwide Multistate Licensing System (“NMLS”) under NMLS ID #2745309.

BLIND PAY SOCIEDADE PRESTADORA DE SERVIÇOS DE ATIVOS VIRTUAIS LTDA. (“BlindPay”) is a Virtual Asset Service Provider (“VASP”) operating in Brazil. The company is presently completing the regulatory adaptation process required of Virtual Asset Service Provider Companies (SPSAV) under Central Bank of Brazil Resolution No. 520/2025, and remains subject to the transitional regime set forth in Article 88 of that Resolution. Registered address: Avenida Princesa Isabel, nº 15, Sala 1405, Edifício Martinho de Freitas, Centro, Vitória/ES, 29010-361.

BlindPay is a stablecoin API that enables individuals and businesses to move money worldwide.