Skip to main content

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."
}
FieldTypeDescription
webhookIdstring (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.
typestringThe event type (see Event Types below).
accountIdstring (uuid)The account the event is about.
timestampstring (datetime)When the event occurred. A retry or a resend keeps the original value.
detailsobjectEvent-specific data. See the webhook guides for each event's fields.
systemNotesstringAdvisory 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.

HeaderDescription
X-BlockWyre-SignatureDetached JWS signature (RS512) of the raw request body.
X-BlockWyre-Signature-VersionSignature format version. Current version: 20260209.
X-BlockWyre-TimestampUnix timestamp (seconds) of this delivery attempt. Set on every attempt and not signed.
X-BlockWyre-Webhook-IDSame value as webhookId in the body.
X-BlockWyre-Retry-CountAttempts made before this one, from 0 to 5. A resent delivery starts again at 0.
X-Tenant-IDYour workspace ID (UUID).
Content-TypeAlways 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 TypeCategoryDescription
account_createdaccountsA new account was created.
account_status_updatedaccountsThe account status changed (for example, pending to active).
kyc_status_updatedcomplianceThe KYC verification status changed.
kyc_needs_updatecomplianceThe KYC verification needs more information. Sent instead of kyc_status_updated when the new status is needs_update.
kyc_verification_submittedcomplianceA KYC verification was submitted for review.
kyc_verification_signedcomplianceThe account holder accepted the terms and conditions or the privacy policy.
kyc_document_upload_receivedcomplianceThe verification provider acknowledged a document.
kyc_document_uploadedcomplianceDocuments were uploaded for a KYC verification.
kyc_verification_completedcomplianceThe applicant completed the verification flow. Carries no outcome: the result arrives as kyc_status_updated.
kyb_verification_submittedcomplianceA KYB (business) verification was submitted for review.
kyb_document_uploadedcomplianceA 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 TypeCategoryDescription
crypto_transaction_createdcryptoA crypto transaction was created: a withdrawal (details.type withdraw) or an incoming deposit (details.type deposit).
crypto_transaction_status_updatedcryptoA crypto transaction's status changed.
crypto_wallet_createdwalletsA new crypto wallet was created.
crypto_beneficiary_createdwalletsA crypto beneficiary (saved destination) was added.
crypto_beneficiary_updatedwalletsA crypto beneficiary was updated.
crypto_beneficiary_deletedwalletsA crypto beneficiary was removed.

Banking Events​

Event TypeCategoryDescription
bank_transaction_createdbankingA bank transaction was created: a withdrawal (details.type withdraw) or an incoming deposit (details.type deposit).
bank_transaction_status_updatedbankingA bank transaction's status changed.
ach_pull_createdbankingAn ACH pull was accepted (v3). details is the pull in the v3 format: see ACH Pull Webhooks.
ach_pull_status_updatedbankingAn ACH pull's status changed (v3).

Trade Events​

Event TypeCategoryDescription
trade_transaction_createdtradeA trade was created.
trade_transaction_status_updatedtradeA 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:

EnvironmentJWKS URLWebhook signing key kid
Sandboxhttps://api-sandbox.blockwyre.xyz/.well-known/jwks.jsonbw-sandbox-20260915
Productionhttps://api.blockwyre.com/.well-known/jwks.jsonbw-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​

  1. 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.
  2. Split the X-BlockWyre-Signature header (format: header..signature) at the ...
  3. Base64url-encode the raw body.
  4. Rebuild the full JWS: header.encoded_body.signature.
  5. Verify the RS512 signature with the JWKS key whose kid matches 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-Timestamp is not signed and is set fresh on every attempt. Use it only as a freshness hint, not as replay protection.
  • X-Tenant-ID is not signed either. Treat it as a routing hint.
  • Always use HTTPS for your webhook endpoint.

Best Practices​

  • Acknowledge quickly with a 2xx (for example 204 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, 302 or 303 turns the delivery into a GET without 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 (disabledAt in 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:

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!