Webhooks Guide
Overview
Webhooks allow you to receive real-time notifications about specific events. When an event occurs, a webhook is sent to all configured targets.
Do not rely solely on webhooks for final state. Always verify the current status via the API to ensure consistency.
Webhooks Functionality
Configuration
- You can configure up to 5 targets per workspace. See Managing Webhook Targets.
- Each target receives a webhook when an event occurs.
- Each delivery attempt times out after 30 seconds.
- A webhook is queued 1 second after the event. Status updates for crypto, bank and trade transactions are queued after 5 seconds instead, so the transaction has settled before you are told about it.
Error Handling
A delivery counts as successful on a 2xx or 3xx response. Anything else — a
4xx, a 5xx, a timeout or a connection failure — counts as a failure and is
retried.
- Failed deliveries are retried up to 5 times with exponential backoff.
- After the fifth failure the target is disabled and receives nothing further.
- Re-enable it with
PATCH /api/v2/webhooks/targets/{targetId}/enable. You do not need to delete and recreate it, and doing so loses the target's id.
Headers
Each webhook request includes headers for authentication and traceability:
| Header | Description |
|---|---|
X-BlockWyre-Signature | Detached JWS signature (RS512). See Validating Webhooks. |
X-BlockWyre-Signature-Version | Signature version. Current version: 20260209. |
X-BlockWyre-Timestamp | Unix timestamp (seconds) when the webhook was sent |
X-BlockWyre-Webhook-ID | Unique webhook identifier (UUID) |
X-BlockWyre-Retry-Count | Current retry attempt number (starts at 0) |
X-Tenant-ID | Your workspace/tenant identifier |
Content-Type | Always application/json |
Example Headers
POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
X-BlockWyre-Signature: eyJhbGciOiJSUzUxMiIsImtpZCI6ImJsb2Nrd3lyZS13ZWJob29rLWtleS0xIn0..BASE64URL_SIGNATURE
X-BlockWyre-Signature-Version: 20260209
X-BlockWyre-Timestamp: 1701705600
X-BlockWyre-Webhook-ID: 00000000-0000-0000-0000-000000000000
X-BlockWyre-Retry-Count: 0
X-Tenant-ID: your-workspace-id
Webhook Payload Structure
All webhooks follow this base structure:
{
"webhookId": "00000000-0000-0000-0000-000000000000",
"type": "webhook_type",
"accountId": "00000000-0000-0000-0000-000000000000",
"timestamp": "2025-01-01T00:00: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."
}
Webhook Events
Account & KYC Events
| Event Type | Description |
|---|---|
account_created | A new account has been created |
account_status_updated | The account status has changed |
kyc_status_updated | The KYC verification status has changed |
kyc_needs_update | Additional KYC information is required |
bank_account_link | Bank account linking status has changed |
For detailed payload samples and field descriptions, see Account & KYC Webhooks.
Crypto Transaction Events
| Event Type | Description |
|---|---|
crypto_transaction_created | A new crypto transaction (withdrawal) has been initiated |
crypto_transaction_received | An incoming crypto deposit has been detected |
crypto_transaction_status_updated | The status of a crypto transaction has changed |
crypto_wallet_created | A new crypto wallet has been created |
crypto_beneficiary_created | A new crypto beneficiary has been created |
crypto_beneficiary_updated | A crypto beneficiary has been updated |
crypto_beneficiary_deleted | A crypto beneficiary has been deleted |
For detailed payload samples and field descriptions, see Crypto Webhooks.
Bank Transaction Events
| Event Type | Description |
|---|---|
bank_transaction_created | A new bank transaction (withdrawal) has been initiated |
bank_transaction_received | An incoming bank deposit has been detected |
bank_transaction_status_updated | The status of a bank transaction has changed |
For detailed payload samples and field descriptions, see Banking Webhooks.
Trade Events
| Event Type | Description |
|---|---|
trade_transaction_created | A new trade has been initiated |
trade_transaction_status_updated | The status of a trade has changed |
For detailed payload samples and field descriptions, see Trade Webhooks.
Card Events
| Event Type | Description |
|---|---|
card_added | A new credit card has been added to an account |
card_status_updated | The status of a credit card has changed |
card_deleted | A credit card has been deleted from an account |
card_transaction_created | A new card transaction has been initiated |
card_transaction_status_updated | The status of a card transaction has changed |
For detailed payload samples and field descriptions, see Card Webhooks.
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!