[{"data":1,"prerenderedAt":163},["ShallowReactive",2],{"content-\u002Fprompts\u002Fintegrate-webhooks":3,"prompts-category-integrations":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\u002Fintegrate-webhooks.md","Integrate webhooks end to end",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 to build the webhook infrastructure every BlindPay integration should be driven by.",[15,16,18],"h2",{"id":17},"prompt","Prompt",[20,21,27],"pre",{"className":22,"code":24,"language":25,"meta":26},[23],"language-text","You are building the webhook layer for my BlindPay integration.\n\nBefore writing code, 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- The OpenAPI spec: curl https:\u002F\u002Fapi.blindpay.com\u002Fdoc\n\nBuild:\n1. Endpoint registration: POST \u002Fv1\u002Finstances\u002F{instance_id}\u002Fwebhook-endpoints with my https URL and an explicit events list (empty array means all events). Fetch the signing secret via GET \u002Fv1\u002Finstances\u002F{instance_id}\u002Fwebhook-endpoints\u002F{endpoint_id}\u002Fsecret.\n2. Signature verification, exactly per the docs: build the signed content as \"{svix-id}.{svix-timestamp}.{raw request body}\" using the raw bytes (never re-serialized JSON), HMAC-SHA256 keyed with the base64-decoded portion of the whsec_ secret, base64 the digest, then compare against each space-delimited \"v1,...\" candidate in svix-signature using a constant-time comparison. Reject if the timestamp is more than 5 minutes from now.\n3. Dedup and retries: svix-id is stable across retries, so use it as the idempotency key. Return 2xx fast and process asynchronously; non-2xx responses are retried with backoff.\n4. Event routing for the catalog: customer.new\u002Fupdate\u002Fdelete, bankAccount.new, blockchainWallet.new, tos.accept, payin.new\u002Fupdate\u002Fcomplete, payout.new\u002Fupdate\u002Fcomplete, payout.partnerFee, virtualAccount.new\u002Fcomplete, transfer.new\u002Fcomplete, wallet.new, wallet.inbound, limitIncrease.new\u002Fupdate. Every payload carries a webhook_event field; route on it and log unknown events instead of failing.\n5. A local development story: a tunnel or the dashboard's event replay for re-delivering events while testing.\n\nConstraints:\n- The verification code must be covered by unit tests with a known secret and fixture payload, including a tampered-body case and an expired-timestamp case.\n- Never log full payloads containing PII; log event type, svix-id, and resource IDs.\n\nDeliverables: registration script or setup code, verification middleware, an idempotent event router with per-event handlers stubbed, and the unit tests described above.\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 with your stack details (framework and queue system if any).",[38,42,43],{},"Point the agent at your endpoint URL; use a tunnel for local development.",[38,45,46],{},"Replay events from the BlindPay dashboard to test handlers 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},"integrations","2026-08-26","Register endpoints, verify Svix signatures correctly, deduplicate retries, and drive payment state from the full BlindPay event catalog.","md",false,{},true,"\u002Fprompts\u002Fintegrate-webhooks",[92],"webhooks","---\ntitle: \"Integrate webhooks end to end\"\ndescription: \"Register endpoints, verify Svix signatures correctly, deduplicate retries, and drive payment state from the full BlindPay event catalog.\"\ndate: \"2026-08-26\"\ncategory: \"integrations\"\nproducts: [\"webhooks\"]\n---\n\nPaste this prompt into your coding agent to build the webhook infrastructure every BlindPay integration should be driven by.\n\n## Prompt\n\n```text\nYou are building the webhook layer for my BlindPay integration.\n\nBefore writing code, 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- The OpenAPI spec: curl https:\u002F\u002Fapi.blindpay.com\u002Fdoc\n\nBuild:\n1. Endpoint registration: POST \u002Fv1\u002Finstances\u002F{instance_id}\u002Fwebhook-endpoints with my https URL and an explicit events list (empty array means all events). Fetch the signing secret via GET \u002Fv1\u002Finstances\u002F{instance_id}\u002Fwebhook-endpoints\u002F{endpoint_id}\u002Fsecret.\n2. Signature verification, exactly per the docs: build the signed content as \"{svix-id}.{svix-timestamp}.{raw request body}\" using the raw bytes (never re-serialized JSON), HMAC-SHA256 keyed with the base64-decoded portion of the whsec_ secret, base64 the digest, then compare against each space-delimited \"v1,...\" candidate in svix-signature using a constant-time comparison. Reject if the timestamp is more than 5 minutes from now.\n3. Dedup and retries: svix-id is stable across retries, so use it as the idempotency key. Return 2xx fast and process asynchronously; non-2xx responses are retried with backoff.\n4. Event routing for the catalog: customer.new\u002Fupdate\u002Fdelete, bankAccount.new, blockchainWallet.new, tos.accept, payin.new\u002Fupdate\u002Fcomplete, payout.new\u002Fupdate\u002Fcomplete, payout.partnerFee, virtualAccount.new\u002Fcomplete, transfer.new\u002Fcomplete, wallet.new, wallet.inbound, limitIncrease.new\u002Fupdate. Every payload carries a webhook_event field; route on it and log unknown events instead of failing.\n5. A local development story: a tunnel or the dashboard's event replay for re-delivering events while testing.\n\nConstraints:\n- The verification code must be covered by unit tests with a known secret and fixture payload, including a tampered-body case and an expired-timestamp case.\n- Never log full payloads containing PII; log event type, svix-id, and resource IDs.\n\nDeliverables: registration script or setup code, verification middleware, an idempotent event router with per-event handlers stubbed, and the unit tests described above.\n```\n\n## How to use\n\n1. Paste the prompt with your stack details (framework and queue system if any).\n2. Point the agent at your endpoint URL; use a tunnel for local development.\n3. Replay events from the BlindPay dashboard to test handlers 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\u002Fintegrate-webhooks","DYGtkXXuvzJpsf3u7JXCYb_TLljZGfNgW1C8mIvgwsE",[98,102,106,110,114,118,122,126,130,134,138,142,146,150,154,158,159],{"path":99,"title":100,"description":101},"\u002Fprompts\u002Fbuild-contractor-payouts","Build a global contractor payout product","Compose onboarding, bank accounts, quotes, payouts, and reconciliation into a complete pay-your-contractors feature across Pix, SPEI, SEPA, and ACH.",{"path":103,"title":104,"description":105},"\u002Fprompts\u002Fconnect-ai-agent-mcp","Connect an AI agent with the MCP server","Wire Claude, Cursor, or any MCP-compatible host to the BlindPay API with the official MCP server and agent skills, with guardrails for money movement.",{"path":107,"title":108,"description":109},"\u002Fprompts\u002Fintegrate-external-wallet-payouts","Fund payouts from external wallets","Let customers pay out from their own EVM, Solana, or Stellar wallets: signed-message registration plus the on-chain authorization step per chain.",{"path":111,"title":112,"description":113},"\u002Fprompts\u002Fintegrate-circle-wallets","Integrate Circle wallets with BlindPay","Fund BlindPay payouts from Circle developer-controlled wallets: sign the registration challenge and the ERC-20 approve through Circle's API instead of a browser wallet.",{"path":115,"title":116,"description":117},"\u002Fprompts\u002Fintegrate-dfns","Integrate Dfns with BlindPay","Fund BlindPay stablecoin payouts from Dfns MPC wallets: sign the registration challenge and the ERC-20 approve through Dfns's User Action Signature flow.",{"path":119,"title":120,"description":121},"\u002Fprompts\u002Fintegrate-fireblocks","Integrate Fireblocks with BlindPay","Fund BlindPay stablecoin payouts from Fireblocks vault accounts: MPC-signed wallet registration and the ERC-20 approve through Fireblocks' transactions API.",{"path":123,"title":124,"description":125},"\u002Fprompts\u002Fintegrate-privy","Integrate Privy with BlindPay","Fund BlindPay stablecoin payouts from Privy Server Wallets: sign the registration challenge and the ERC-20 approve through Privy's wallet RPC endpoint.",{"path":127,"title":128,"description":129},"\u002Fprompts\u002Fintegrate-virtual-accounts","Integrate US virtual accounts","Give each customer a named US bank account with ACH, RTP, wire, and SWIFT details that settles automatically to USDC or USDT in their wallet.",{"path":131,"title":132,"description":133},"\u002Fprompts\u002Fintegrate-utila","Integrate Utila with BlindPay","Fund BlindPay payouts from Utila MPC vaults: sign the wallet-registration challenge and the ERC-20 approve through Utila's service-account API, with async transaction confirmation handled.",{"path":135,"title":136,"description":137},"\u002Fprompts\u002Fintegrate-customer-onboarding","Integrate customer onboarding with KYC and KYB","Build the full onboarding pipeline: terms of service, individual and business customers, document uploads, RFI handling, and status webhooks.",{"path":139,"title":140,"description":141},"\u002Fprompts\u002Fintegrate-offramp-wallets","Integrate offramp wallets for auto-conversion","Give each bank account a dedicated crypto deposit address: stablecoins sent to it convert and pay out to the linked bank account automatically.",{"path":143,"title":144,"description":145},"\u002Fprompts\u002Fintegrate-payins","Integrate payins from bank transfers to stablecoins","Accept Pix, ACH, wire, SPEI, and other local bank transfers and settle them as USDC or USDT in a wallet, with quotes, payment instructions, and webhooks.",{"path":147,"title":148,"description":149},"\u002Fprompts\u002Fintegrate-quotes-fx","Integrate quotes and FX handling","Handle payin, payout, and transfer quotes correctly: expiry windows, currency_type conventions, fees, and displaying rates to users.",{"path":151,"title":152,"description":153},"\u002Fprompts\u002Fintegrate-stablecoin-payouts","Integrate stablecoin payouts end to end","Build a complete stablecoin to fiat payout flow: customer onboarding, bank accounts, quotes, and payout execution over Pix, ACH, SPEI, SEPA, and more.",{"path":155,"title":156,"description":157},"\u002Fprompts\u002Fintegrate-wallet-transfers","Integrate wallet transfers and cross-chain USDC","Move stablecoins from managed wallets to any address with transfer quotes, including cross-chain USDC over Circle CCTP v2.",{"path":90,"title":5,"description":85},{"path":160,"title":161,"description":162},"\u002Fprompts\u002Fintegrate-payables","Pay boletos and Brazilian bills with payables","Register boletos, arrecadacao slips, and PIX codes as payables and settle them from stablecoins through the quote-and-execute flow.",1787868849662]