Webhooks
Overview
BlockWyre uses webhooks to notify your application when events occur on the platform. When an event happens, a POST request with a JSON payload describing it is sent to each active webhook target that receives that event.
For a walkthrough, see the Webhooks Guide, Validating Webhooks and Receiving Webhooks in Production.
Webhook Targets
Each workspace can register up to 5 webhook target URLs. Which events a target receives depends on where it was set up:
- A target created through the Webhook Targets API (
/api/v2/webhooks/targets) receives every event. - A target created or edited in the dashboard (Notifications › Webhook) receives only the categories selected for it:
accounts,compliance,banking,crypto,wallets,trade. The event tables below list each event's category.
Both manage the same targets: a target created in one place can be listed, enabled and deleted in the other.
Webhook Payload
All webhook payloads follow the same structure:
{
"webhookId": "00000000-0000-0000-0000-000000000000",
"type": "account_status_updated",
"accountId": "00000000-0000-0000-0000-000000000000",
"timestamp": "2026-01-10T09:30:00Z",
"details": {},
"systemNotes": "Do not rely solely on this webhook for final state. Always verify the current status via the API to ensure consistency. Consult the developer documentation and guides for more information."
}
| Field | Type | Description |
|---|---|---|
webhookId | string (uuid) | Identifies this event's delivery to this target. Unique per event per target, and the same on every retry and resend of it. Deduplicate on it. |
type | string | The event type (see Event Types below). |
accountId | string (uuid) | The account the event is about. |
timestamp | string (datetime) | When the event occurred. A retry or a resend keeps the original value. |
details | object | Event-specific data. See the webhook guides for each event's fields. |
systemNotes | string | Advisory note about the webhook. |
Request Headers
Each webhook request includes the following headers. Only the body is signed: none of these headers is covered by the signature.
| Header | Description |
|---|---|
X-BlockWyre-Signature | Detached JWS signature (RS512) of the raw request body. |
X-BlockWyre-Signature-Version | Signature format version. Current version: 20260209. |
X-BlockWyre-Timestamp | Unix timestamp (seconds) of this delivery attempt. Set on every attempt and not signed. |
X-BlockWyre-Webhook-ID | Same value as webhookId in the body. |
X-BlockWyre-Retry-Count | Attempts made before this one, from 0 to 5. A resent delivery starts again at 0. |
X-Tenant-ID | Your workspace ID (UUID). |
Content-Type | Always application/json. |
Event Types
These are all the events BlockWyre sends. The category is what a target set up in the dashboard selects.
Account, KYC & KYB Events
| Event Type | Category | Description |
|---|---|---|
account_created | accounts | A new account was created. |
account_status_updated | accounts | The account status changed (for example, pending to active). |
kyc_status_updated | compliance | The KYC verification status changed. |
kyc_needs_update | compliance | The KYC verification needs more information. Sent instead of kyc_status_updated when the new status is needs_update. |
kyc_verification_submitted | compliance | A KYC verification was submitted for review. |
kyc_verification_signed | compliance | The account holder accepted the terms and conditions or the privacy policy. |
kyc_document_upload_received | compliance | The verification provider acknowledged a document. |
kyc_document_uploaded | compliance | Documents were uploaded for a KYC verification. |
kyc_verification_completed | compliance | The applicant completed the verification flow. Carries no outcome: the result arrives as kyc_status_updated. |
kyb_verification_submitted | compliance | A KYB (business) verification was submitted for review. |
kyb_document_uploaded | compliance | A document was uploaded for a KYB verification. |
These events are sent by the /api/v2 account, KYC and KYB flows. The /v3 customers, KYC and KYB endpoints send none of them yet: read the record through the API.
Crypto Events
| Event Type | Category | Description |
|---|---|---|
crypto_transaction_created | crypto | A crypto transaction was created: a withdrawal (details.type withdraw) or an incoming deposit (details.type deposit). |
crypto_transaction_status_updated | crypto | A crypto transaction's status changed. |
crypto_wallet_created | wallets | A new crypto wallet was created. |
crypto_beneficiary_created | wallets | A crypto beneficiary (saved destination) was added. |
crypto_beneficiary_updated | wallets | A crypto beneficiary was updated. |
crypto_beneficiary_deleted | wallets | A crypto beneficiary was removed. |
Banking Events
| Event Type | Category | Description |
|---|---|---|
bank_transaction_created | banking | A bank transaction was created: a withdrawal (details.type withdraw) or an incoming deposit (details.type deposit). |
bank_transaction_status_updated | banking | A bank transaction's status changed. |
ach_pull_created | banking | An ACH pull was accepted (v3). details is the pull in the v3 format: see ACH Pull Webhooks. |
ach_pull_status_updated | banking | An ACH pull's status changed (v3). |
Trade Events
| Event Type | Category | Description |
|---|---|---|
trade_transaction_created | trade | A trade was created. |
trade_transaction_status_updated | trade | A trade's status changed. |
There is no separate "received" event for deposits, and no card events: switch on type and, for transactions, on details.type.
Retry Policy
A delivery counts as delivered when your endpoint answers any 2xx or 3xx status. Anything else — a 4xx, a 5xx, no answer within 30 seconds, or a connection failure — is retried with exponential backoff: up to 6 attempts in all (the first and 5 retries), about 7 to 14 minutes from the first attempt to the sixth.
Redirects are followed before the answer is judged, up to 3 in a row, each to a public address only. A 307 or 308 re-sends the same POST with its body; a 301, 302 or 303 is followed as a GET without a body, which cannot be verified. A 3xx counts as delivered only when it is not followed, such as a fourth redirect in a row.
A repeat within 5 minutes is not sent: when the same event about the same object (for a status update, to the same new status) was already sent to a target in the last 5 minutes, that target does not receive it again.
A target is automatically disabled when one delivery fails all six attempts. A disabled target receives nothing until it is re-enabled; events that occur while it is disabled are not sent to it later.
To re-enable a disabled target, use the Enable Webhook Target endpoint.
Security
Signature Verification
Every webhook includes a detached JWS signature (RS512) of the raw request body in the X-BlockWyre-Signature header. Verify it with the public keys published at the JWKS endpoint of the environment that sent the webhook:
| Environment | JWKS URL | Webhook signing key kid |
|---|---|---|
| Sandbox | https://api-sandbox.blockwyre.xyz/.well-known/jwks.json | bw-sandbox-20260915 |
| Production | https://api.blockwyre.com/.well-known/jwks.json | bw-20260201 |
The two environments sign with different keys: a sandbox webhook does not verify against the production JWKS, nor the reverse. The endpoint is public (no authentication) and returns Cache-Control: public, max-age=3600. Select the key by the signature's kid, never by its position in the list.
Verification Steps
- Read the request body as raw bytes, before any JSON parsing. Never re-serialize parsed JSON: the bytes change and the signature no longer matches.
- Split the
X-BlockWyre-Signatureheader (format:header..signature) at the... - Base64url-encode the raw body.
- Rebuild the full JWS:
header.encoded_body.signature. - Verify the RS512 signature with the JWKS key whose
kidmatches the JWS header's.
See Validating Webhooks for a code example.
Additional Security
- Deduplicate on
webhookId: it is part of the signed body, so it is your protection against a replayed request. X-BlockWyre-Timestampis not signed and is set fresh on every attempt. Use it only as a freshness hint, not as replay protection.X-Tenant-IDis not signed either. Treat it as a routing hint.- Always use HTTPS for your webhook endpoint.
Best Practices
- Acknowledge quickly with a
2xx(for example204 No Content) and process the payload asynchronously; an attempt times out after 30 seconds. - Register the final URL of your endpoint, not one that redirects: a
301,302or303turns the delivery into aGETwithout a body. - Always verify the current state via the API — do not rely solely on webhooks for final state.
- Deduplicate on
webhookId: a retry can arrive after your handler already succeeded. - Do not depend on delivery order. Events about the same object are usually delivered in order, but a retried event can arrive after a newer one.
- Monitor your targets (
disabledAtin the target list) so a disabled target does not go unnoticed.
Support and Resources
If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.
Stay Updated
Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:
- Instagram: BlockWyre Instagram
- Twitter: BlockWyre Twitter
- Facebook: BlockWyre Facebook
- LinkedIn: BlockWyre LinkedIn
We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!