Webhooks & Events
Planbok uses a high-performance, asynchronous webhook system to provide real-time notifications about critical events within your organization. This allows your backend to stay synchronized with transaction statuses, wallet creations, and security events without polling our API.
Event Types
We support a wide range of event types to cover every aspect of your wallet infrastructure:
Transaction Events
Notify you as a transaction moves through its lifecycle.
transaction.created: A new transaction has been initiated and is awaiting signing.transaction.signed: The 2-of-2 MPC ceremony is complete and the transaction is signed.transaction.broadcast: The signed transaction has been submitted to the blockchain network.transaction.confirmed: The transaction has been successfully included in a block.transaction.failed: The transaction failed to sign, broadcast, or was rejected by the network.transaction.accelerated: A "Replace-By-Fee" operation was triggered for an EVM or Bitcoin transaction.transaction.cancelled: A pending transaction was successfully cancelled.
Wallet & Customer Events
Real-time updates as you scale your infrastructure.
wallet.created: A new multi-chain wallet has been generated for a user.customer.created: A new customer identity has been registered in your organization.customer.pin_setup: A customer has successfully configured their self-custody PIN.
Security Events
Critical alerts to help you maintain a secure environment.
customer.locked_out: Multiple failed PIN attempts detected for a customer.customer.recovery_initiated: A security question recovery flow has started.customer.recovery_completed: A customer has successfully recovered their wallet access.
Reliability & Idempotency
To ensure that your system remains consistent even in the event of network instability, Planbok implements several reliability features:
1. Idempotency Keys
Every webhook payload includes a unique idempotencyKey. This key is generated based on the organization ID, event type, and entity ID.
- Dedup Window: If multiple identical events occur within a 1-minute window, they will share the same idempotency key, allowing your backend to safely ignore duplicates.
2. Guaranteed Delivery
Webhooks are managed by a robust queuing system (Redis-backed). If your server is down or returns a non-2xx status code, our system will automatically retry the delivery with exponential backoff.
Security Best Practices
Webhook Signing
Webhook Signing
Each webhook request includes a X-Webhook-Signature header and a X-Webhook-Timestamp. The signature is an HMAC-SHA256 hash of the string ${timestamp}.${payload}, signed with your organization's unique webhook secret.
To prevent replay attacks, you should verify that the X-Webhook-Timestamp is within a reasonable window (e.g., 5 minutes) and then recompute the signature using the request body and the timestamp provided in the header.
Data Redaction
For privacy and security compliance, sensitive data (like full email addresses or internal metadata) is automatically redacted from webhook payloads unless explicitly required for the event's purpose.
Payload Example
Code