Webhooks

Overview

BlockWyre uses webhooks to notify your application in real-time when events occur on the platform. When a subscribed event is triggered, a POST request is sent to each of your configured webhook target URLs with a JSON payload describing the event.

Webhook Targets

Each workspace can register up to 5 webhook target URLs. All active targets receive every webhook event. Manage your targets using the Webhook Targets API.

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": "2025-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."
}

Field	Type	Description
webhookId	string (uuid)	Unique identifier for this webhook delivery.
type	string	The event type (see Event Types below).
accountId	string (uuid)	The account associated with the event.
timestamp	string (datetime)	When the event occurred.
details	object	Event-specific data.
systemNotes	string	Advisory note about the webhook.

Request Headers

Each webhook request includes the following headers:

Header	Description
X-BlockWyre-Signature	Detached JWS signature (RS512) for payload verification.
X-BlockWyre-Signature-Version	Signature format version (e.g., 20260209).
X-BlockWyre-Timestamp	Unix timestamp (seconds) when the webhook was sent.
X-BlockWyre-Webhook-ID	Unique ID for this webhook delivery.
X-BlockWyre-Retry-Count	Number of retry attempts (starts at 0).
X-Tenant-ID	Your workspace/tenant identifier.
Content-Type	Always application/json.

Event Types

Account & KYC Events

Event Type	Description
account_created	A new account was created.
account_status_updated	Account status changed (e.g., pending to active).
kyc_status_updated	KYC verification status changed.
kyc_needs_update	Additional information required for KYC.
kyc_verification_submitted	KYC verification was submitted.
kyc_verification_signed	Account holder signed terms and conditions.
kyc_document_upload_received	Document upload event received from provider.
kyc_document_uploaded	Documents uploaded successfully.
kyc_verification_completed	KYC verification process completed.
kyb_verification_submitted	KYB verification was submitted.
kyb_document_uploaded	Business document uploaded successfully.
bank_account_link	Bank account linked to the account.

Crypto Events

Event Type	Description
crypto_transaction_created	Crypto transaction initiated.
crypto_transaction_received	Incoming crypto transaction detected.
crypto_transaction_status_updated	Crypto transaction status changed.
crypto_wallet_created	New crypto wallet created.
crypto_beneficiary_created	Crypto beneficiary added.
crypto_beneficiary_updated	Crypto beneficiary updated.
crypto_beneficiary_deleted	Crypto beneficiary removed.

Banking Events

Event Type	Description
bank_transaction_created	Bank transaction initiated.
bank_transaction_received	Incoming bank transaction detected.
bank_transaction_status_updated	Bank transaction status changed.

Trade Events

Event Type	Description
trade_transaction_created	Trade transaction initiated.
trade_transaction_status_updated	Trade transaction status changed.

Retry Policy

If your endpoint fails to respond with a 2xx status code, BlockWyre retries up to 5 times with exponential backoff intervals. After all retries are exhausted, the webhook target is automatically disabled.

To re-enable a disabled target, use the Enable Webhook Target endpoint.

Security

Signature Verification

Every webhook includes a detached JWS signature (RS512 algorithm) in the X-BlockWyre-Signature header. Verify signatures using the public key available at:

GET /.well-known/jwks.json

This endpoint is public (no authentication required) and returns a JWKS (JSON Web Key Set) with a 1-hour cache.

Verification Steps

1. Fetch the public key from /.well-known/jwks.json.
2. Extract the X-BlockWyre-Signature header (format: header..signature).
3. Base64url-encode the raw request body.
4. Reconstruct the full JWS: header.encoded_payload.signature.
5. Verify the RS512 signature using the public key matched by kid.

Additional Security

• Validate the X-Tenant-ID header matches your expected workspace ID.
• Verify the X-BlockWyre-Timestamp is within an acceptable time window (recommended: 5 minutes).
• Always use HTTPS for your webhook endpoint.

Best Practices

• Return a 204 No Content response to acknowledge receipt.
• Process webhook payloads asynchronously to avoid timeouts.
• Always verify the current state via the API — do not rely solely on webhooks for final state.
• Implement idempotency using the webhookId to handle potential duplicate deliveries.
• Monitor your endpoint health to avoid automatic disabling due to failures.

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!