[{"data":1,"prerenderedAt":107},["ShallowReactive",2],{"content-\u002Fprompts\u002Fdebug-webhooks":3,"prompts-category-setup":97},{"id":4,"title":5,"author":6,"body":7,"categories":6,"category":83,"categoryType":6,"date":84,"description":85,"extension":86,"faq":6,"howto":6,"isBlog":87,"isChangelog":87,"meta":88,"navigation":89,"path":90,"pillar":87,"products":91,"rawbody":93,"seo":94,"stem":95,"thumbnail":6,"updated":6,"__hash__":96},"content\u002Fprompts\u002Fdebug-webhooks.md","Debug webhook delivery and verification",null,{"type":8,"value":9,"toc":77},"minimark",[10,14,19,30,34,47,51],[11,12,13],"p",{},"Paste this prompt into your coding agent when webhooks are not arriving or signature verification keeps failing.",[15,16,18],"h2",{"id":17},"prompt","Prompt",[20,21,27],"pre",{"className":22,"code":24,"language":25,"meta":26},[23],"language-text","My BlindPay webhooks are failing (not arriving, or failing signature verification). Diagnose and fix the problem.\n\nBefore debugging, read these sources and follow them over any prior knowledge:\n- https:\u002F\u002Fblindpay.com\u002Fdocs\u002Fllms.txt (read the webhooks, webhook verification, and webhook events pages)\n\nWork through this checklist against my code and configuration, in order:\n1. Endpoint registration: list my webhook endpoints (GET \u002Fv1\u002Finstances\u002F{instance_id}\u002Fwebhook-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).\n2. Secret mismatch: confirm the whsec_ secret in my config was fetched for this exact endpoint ID via GET \u002Fv1\u002Finstances\u002F{instance_id}\u002Fwebhook-endpoints\u002F{endpoint_id}\u002Fsecret. Each endpoint has its own secret; a secret from another endpoint or instance verifies nothing.\n3. 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.\n4. 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,\u003Csig>\"; 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.\n5. 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.\n6. 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.\n\nDeliverables: the specific root cause found, the fix, and the signature verification unit tests so this class of bug cannot silently return.\n","text","",[28,29,24],"code",{"__ignoreMap":26},[15,31,33],{"id":32},"how-to-use","How to use",[35,36,37,41,44],"ol",{},[38,39,40],"li",{},"Paste the prompt and give the agent access to your webhook handler code and (redacted) config.",[38,42,43],{},"Have a real failing request's headers handy if you captured them; they speed up diagnosis.",[38,45,46],{},"Use the dashboard's event replay to confirm the fix without creating new payments.",[15,48,50],{"id":49},"related-docs","Related docs",[52,53,54,63,70],"ul",{},[38,55,56],{},[57,58,62],"a",{"href":59,"rel":60},"https:\u002F\u002Fblindpay.com\u002Fdocs\u002Flearn\u002Fwebhooks",[61],"nofollow","Webhooks",[38,64,65],{},[57,66,69],{"href":67,"rel":68},"https:\u002F\u002Fblindpay.com\u002Fdocs\u002Flearn\u002Fwebhooks-verification",[61],"Signature verification",[38,71,72],{},[57,73,76],{"href":74,"rel":75},"https:\u002F\u002Fblindpay.com\u002Fdocs\u002Flearn\u002Fwebhooks-events",[61],"Event catalog",{"title":26,"searchDepth":78,"depth":78,"links":79},2,[80,81,82],{"id":17,"depth":78,"text":18},{"id":32,"depth":78,"text":33},{"id":49,"depth":78,"text":50},"setup","2026-08-26","Diagnose missing or failing BlindPay webhooks: endpoint config, signature mismatches, raw-body pitfalls, retries, and replay.","md",false,{},true,"\u002Fprompts\u002Fdebug-webhooks",[92],"webhooks","---\ntitle: \"Debug webhook delivery and verification\"\ndescription: \"Diagnose missing or failing BlindPay webhooks: endpoint config, signature mismatches, raw-body pitfalls, retries, and replay.\"\ndate: \"2026-08-26\"\ncategory: \"setup\"\nproducts: [\"webhooks\"]\n---\n\nPaste this prompt into your coding agent when webhooks are not arriving or signature verification keeps failing.\n\n## Prompt\n\n```text\nMy BlindPay webhooks are failing (not arriving, or failing signature verification). Diagnose and fix the problem.\n\nBefore debugging, read these sources and follow them over any prior knowledge:\n- https:\u002F\u002Fblindpay.com\u002Fdocs\u002Fllms.txt (read the webhooks, webhook verification, and webhook events pages)\n\nWork through this checklist against my code and configuration, in order:\n1. Endpoint registration: list my webhook endpoints (GET \u002Fv1\u002Finstances\u002F{instance_id}\u002Fwebhook-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).\n2. Secret mismatch: confirm the whsec_ secret in my config was fetched for this exact endpoint ID via GET \u002Fv1\u002Finstances\u002F{instance_id}\u002Fwebhook-endpoints\u002F{endpoint_id}\u002Fsecret. Each endpoint has its own secret; a secret from another endpoint or instance verifies nothing.\n3. 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.\n4. 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,\u003Csig>\"; 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.\n5. 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.\n6. 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.\n\nDeliverables: the specific root cause found, the fix, and the signature verification unit tests so this class of bug cannot silently return.\n```\n\n## How to use\n\n1. Paste the prompt and give the agent access to your webhook handler code and (redacted) config.\n2. Have a real failing request's headers handy if you captured them; they speed up diagnosis.\n3. Use the dashboard's event replay to confirm the fix without creating new payments.\n\n## Related docs\n\n- [Webhooks](https:\u002F\u002Fblindpay.com\u002Fdocs\u002Flearn\u002Fwebhooks)\n- [Signature verification](https:\u002F\u002Fblindpay.com\u002Fdocs\u002Flearn\u002Fwebhooks-verification)\n- [Event catalog](https:\u002F\u002Fblindpay.com\u002Fdocs\u002Flearn\u002Fwebhooks-events)\n",{"title":5,"description":85},"prompts\u002Fdebug-webhooks","IwKEjeN0ELjYObczo3--rJyHFfB_bTN6DzZrxo7ThJQ",[98,99,103],{"path":90,"title":5,"description":85},{"path":100,"title":101,"description":102},"\u002Fprompts\u002Fsandbox-quickstart","Sandbox quickstart","Stand up a working BlindPay development environment in one session: instance, API key, test customer, funded wallet, and a completed test payout.",{"path":104,"title":105,"description":106},"\u002Fprompts\u002Fsetup-partner-fees","Set up partner fees and revenue share","Attach your own fee to every quote with partner fees, track collected revenue through webhooks, and show users a complete price breakdown.",1787868850910]