---
title: "Integrate webhooks end to end"
description: "Register endpoints, verify Svix signatures correctly, deduplicate retries, and drive payment state from the full BlindPay event catalog."
date: "2026-08-26"
category: "integrations"
products: ["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.

## 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)