Skip to main content
Webhooks allow Dakota Platform to send real-time notifications about events in your account directly to your application.

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 as DAKOTA_WEBHOOK_PUBLIC_KEY.

Dakota Public Keys

Each key is 64 hex characters (32 raw bytes).

Signature Headers

Dakota includes these headers in every webhook request: Full verification implementations for Node.js, Python, Go, Rust, and Java are in Verification Code Examples below.

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

cURL
Response:

Webhook Events

Transaction Events

Transaction lifecycle events fire for auto-account (onramp/offramp/swap) and one-off transactions. There is no separate failed 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). There is no top-level amount — amount-like fields live inside data.object.receipt.
transaction.auto.updated — emitted on every status change or detail update (inspect data.object.status to distinguish processing, completed, failed). When a status change triggered the update, the prior value is included under data.previous_attributes.
transaction.one_off.created / transaction.one_off.updated — same shape, emitted for single-use transactions created via 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.updated
Some customer.kyb_status.updated events include an additional reason_code field that disambiguates a status change driven by the Proof-of-Address (PoA) flow. The field is present only on PoA-related transitions; on all other status updates it is absent. Example payload with reason_code:
customer.created
customer.kyb_application.submitted

Verification 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: Retry behavior:
  • 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 2xx range (200-299)
  • Response is received within 20 seconds
A webhook delivery fails and triggers a retry when:
  • 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 status as 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-ID for 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 timestampscreated and X-Webhook-Timestamp are second-resolution, and two events can share the same value.
If your processing must be strictly serial per resource, queue incoming events by resource ID (e.g. wallet_id, transaction_id) and reorder by status before applying.

Webhook Headers

Every webhook request includes these headers: Use 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
Signature Verification Failing
  • 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)
Duplicate Webhooks
  • 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:

Next Steps

After setting up webhooks:
  1. Testing Your Integration - Test webhook delivery and processing
  2. Transactions - Process transactions that trigger webhook events
  3. Customer Onboarding - Set up KYB status webhooks

API Reference

For detailed endpoint documentation, see: