Webhooks allow Dakota Platform to send real-time notifications about events in your account directly to your application.Documentation Index
Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Instead of constantly polling our API for updates, webhooks deliver event notifications instantly when something happens:- Transaction status changes
- Customer onboarding updates
- Account changes
- System events
Webhook Signature Verification
Dakota signs every webhook with an Ed25519 signature (not HMAC). To verify a delivery, you need Dakota’s public key — set it in your environment asDAKOTA_WEBHOOK_PUBLIC_KEY.
Dakota Public Keys
| Environment | Public Key (hex-encoded) |
|---|---|
| Production | 65b797d688ed4991ecc0d922f360bd9b4c3d68e5a36ce2b1307cc8547bd68be4 |
| Sandbox | 7a2f771f3a7ac9ae2a95066df35dc0261d7ce354214736cc232d70b3c66f8a5f |
Signature Headers
Dakota includes these headers in every webhook request:| Header | Description |
|---|---|
X-Webhook-Signature | Base64-encoded Ed25519 signature over timestamp + body |
X-Webhook-Timestamp | Unix timestamp when the webhook was sent — reject anything older than 5 minutes to prevent replay attacks |
X-Dakota-Event-ID | Unique identifier for the event (optional, useful for idempotency) |
Setting Up Webhooks
1. Create a Webhook Endpoint
Create an endpoint in your application to receive webhook notifications:2. Register Your Webhook
Register your endpoint with Dakota Platform:Webhook Target Fields
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
url | string | ✅ | HTTPS endpoint to receive webhooks | "https://your-app.com/webhooks/dakota" |
global | boolean | ❌ | Whether webhook receives events for all customers (default: false) | false |
event_types | array[string] | ❌ | Array of event types to subscribe to (defaults to all events if not specified) | ["transaction.auto.updated", "customer.kyb_status.updated"] |
cURL
Webhook Events
Transaction Events
Transaction lifecycle events fire for auto-account (onramp/offramp/swap) and one-off transactions. There is no separatefailed event — failure is reflected in the status field of the *.updated event.
transaction.auto.created — emitted when Dakota creates a transaction for an onramp/offramp/swap account (e.g., after detecting a bank deposit).
data.status to distinguish processing, completed, failed).
POST /transactions/one-off. Covers both off-ramp (crypto → fiat with payment_reference support) and swap (crypto → crypto with a destination network override). The one-off artifact is discarded after the transaction completes.
Customer Events
customer.kyb_status.updatedVerification Code Examples
Ed25519 verification implementations — pick your language. See the public keys and required headers in Webhook Signature Verification above.Managing Webhooks
List Webhooks
List all webhook targets configured for your account:cURL
Update Webhook
Update an existing webhook target:cURL
Delete Webhook
Delete a webhook target:cURL
Webhook Delivery
Retry Policy
Dakota automatically retries failed webhook deliveries using exponential backoff over approximately 48 hours:| Attempt | Delay After Failure |
|---|---|
| 1 | 5 minutes |
| 2 | 10 minutes |
| 3 | 15 minutes |
| 4 | 30 minutes |
| 5 | 1 hour |
| 6 | 2 hours |
| 7 | 4 hours |
| 8 | 8 hours |
| 9 | 12 hours |
| 10 (final) | 20 hours |
- Max attempts: 10 total
- Total retry window: ~48 hours
- Timeout per attempt: 20 seconds
Success Criteria
A webhook delivery is considered successful when:- Your endpoint returns an HTTP status code in the
2xxrange (200-299) - Response is received within 20 seconds
- Your endpoint returns a non-2xx status code (4xx, 5xx)
- Connection timeout (20 seconds exceeded)
- Connection refused or DNS failure
Failure Handling
If all 10 delivery attempts fail:- Webhook is marked as permanently failed
- You can view failed webhooks in the dashboard
- Failed webhooks can be manually retried
Event Ordering
Webhooks are not guaranteed to arrive in lifecycle order. Two events fired close together for the same resource (e.g.wallet.transaction.updated for Broadcasted and Success on a fast testnet, or transaction.auto.deposit.received and transaction.auto.deposit.succeeded for an instant rail) may reach your endpoint out of order due to network races, retry timing, and the fact that the envelope created field is second-resolution.
This is most visible in sandbox because testnet broadcasts and the simulate endpoints transition states sub-second. In production, longer chain confirmations and bank-rail latencies usually space the events out enough that ordering is incidental — but the contract still does not guarantee it.
How to handle it:
- Treat
statusas the source of truth, not the order of arrival. Each event carries the full resource state; the latest event by terminal-state semantics wins. - Use
X-Dakota-Event-IDfor idempotency — duplicate deliveries (retries or out-of-order replays) carry the same ID. - For ordered processing, derive a sequence from the resource’s own state machine. For wallet transactions:
Waiting For Signature → Broadcasted → Success | Failed. For auto-account deposits:received → succeeded | failed. If you receive a “later” status before an “earlier” one, accept it; the earlier one is informational. - Don’t strictly require monotonic timestamps —
createdandX-Webhook-Timestampare second-resolution, and two events can share the same value.
wallet_id, transaction_id) and reorder by status before applying.
Webhook Headers
Every webhook request includes these headers:| Header | Description |
|---|---|
Content-Type | application/json |
User-Agent | Dakota-Webhooks/1.0 |
X-Dakota-Event-ID | Unique event identifier (use for idempotency) |
X-Dakota-Event-Type | The type of event (e.g., transaction.auto.updated) |
X-Dakota-Delivery-Attempt | Current attempt number (1-10) |
X-Webhook-Signature | Ed25519 signature (base64 encoded) |
X-Webhook-Timestamp | Unix timestamp when webhook was sent |
X-Dakota-Event-ID for idempotency - it remains the same across all retry attempts for the same event.
Best Practices
Endpoint Requirements
- HTTPS only: Dakota Platform only sends webhooks to HTTPS endpoints
- Fast response: Respond within 30 seconds
- 2xx status codes: Return 200-299 status for successful processing
- Idempotent: Handle duplicate webhooks gracefully
Security
- Always verify webhook signatures
- Use HTTPS for your webhook endpoint
- Validate event data before processing
- Log webhook events for debugging
Processing Best Practices
Implement robust webhook event processing with error handling, retries, and idempotency:Testing Webhooks
Local Development
Use tools like ngrok to expose local endpoints:Webhook Testing
Test your webhook endpoint manually:Troubleshooting
Common Issues
Webhooks Not Received- Check that your endpoint returns 2xx status
- Verify your URL is accessible from the internet
- Ensure HTTPS is properly configured
- Check firewall/proxy settings
- Ensure you’re using Dakota Platform’s correct Ed25519 public key
- Verify the signature calculation matches our Ed25519 implementation
- Check that the timestamp and payload haven’t been modified
- Ensure you’re using the correct header names (
X-Webhook-Signature,X-Webhook-Timestamp)
- Implement idempotency using the event ID
- Store processed event IDs to prevent duplicates
- Use database constraints where possible
Monitoring
- Set up alerts for webhook failures
- Log all webhook events for debugging
- Monitor endpoint response times
- Track webhook delivery success rates
Event Types Reference
Based on the platform’s actual event definitions, here are the available webhook event types:| Event | Description |
|---|---|
| Customer Events | |
customer.created | New customer created |
customer.updated | Customer information updated |
customer.kyb_status.created | Customer KYB status created |
customer.kyb_status.updated | Customer KYB status changed |
customer.kyb_link.created | Customer KYB link created |
customer.kyb_link.updated | Customer KYB link updated |
customer.kyb_application.submitted | Customer KYB application submitted for review |
| Transaction Events | |
transaction.auto.created | Auto account transaction created |
transaction.auto.updated | Auto account transaction updated |
transaction.one_off.created | One-off transaction created |
transaction.one_off.updated | One-off transaction updated |
| Account Events | |
auto_account.created | Auto account created |
auto_account.updated | Auto account updated |
auto_account.deleted | Auto account deleted |
| Wallet Events | |
wallet.created | Non-custodial wallet created |
wallet.updated | Wallet metadata or configuration changed |
wallet.deposit | On-chain deposit detected at a wallet address |
wallet.transaction.created | Wallet transaction submitted |
wallet.transaction.updated | Wallet transaction status or details changed |
wallet.policy.created | Policy created and attached to a wallet |
wallet.policy.updated | Policy rules or metadata updated |
wallet.signer_group.created | Signer group created |
wallet.signer_group.updated | Signer group membership or metadata updated |
| Other Events | |
user.created | User created |
user.updated | User updated |
user.deleted | User deleted |
api_key.created | API key created |
api_key.deleted | API key deleted |
recipient.created | Recipient created |
recipient.updated | Recipient updated |
recipient.deleted | Recipient deleted |
destination.created | Destination created |
destination.deleted | Destination deleted |
target.created | Target created |
target.updated | Target updated |
target.deleted | Target deleted |
exception.created | Exception created |
exception.cleared | Exception cleared |
Next Steps
After setting up webhooks:- Testing Your Integration - Test webhook delivery and processing
- Transactions - Process transactions that trigger webhook events
- Customer Onboarding - Set up KYB status webhooks
API Reference
For detailed endpoint documentation, see:- Webhooks API Reference - Webhook target management
- Events API Reference - Event types and payload formats