Skip to content
Back to Prompts

Integrate webhooks end to end

Register endpoints, verify Svix signatures correctly, deduplicate retries, and drive payment state from the full BlindPay event catalog.

Webhooks

Paste this prompt into your coding agent to build the webhook infrastructure every BlindPay integration should be driven by.

Prompt

text
You are building the webhook layer for my BlindPay integration.

Before writing code, 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)
- The OpenAPI spec: curl https://api.blindpay.com/doc

Build:
1. Endpoint registration: POST /v1/instances/{instance_id}/webhook-endpoints with my https URL and an explicit events list (empty array means all events). Fetch the signing secret via GET /v1/instances/{instance_id}/webhook-endpoints/{endpoint_id}/secret.
2. 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.
3. 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.
4. Event routing for the catalog: customer.new/update/delete, bankAccount.new, blockchainWallet.new, tos.accept, payin.new/update/complete, payout.new/update/complete, payout.partnerFee, virtualAccount.new/complete, transfer.new/complete, wallet.new, wallet.inbound, limitIncrease.new/update. Every payload carries a webhook_event field; route on it and log unknown events instead of failing.
5. A local development story: a tunnel or the dashboard's event replay for re-delivering events while testing.

Constraints:
- 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.
- Never log full payloads containing PII; log event type, svix-id, and resource IDs.

Deliverables: registration script or setup code, verification middleware, an idempotent event router with per-event handlers stubbed, and the unit tests described above.

How to use

  1. Paste the prompt with your stack details (framework and queue system if any).
  2. Point the agent at your endpoint URL; use a tunnel for local development.
  3. Replay events from the BlindPay dashboard to test handlers 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.