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

Environment	Public Key (hex-encoded)
Production	`65b797d688ed4991ecc0d922f360bd9b4c3d68e5a36ce2b1307cc8547bd68be4`
Sandbox	`7a2f771f3a7ac9ae2a95066df35dc0261d7ce354214736cc232d70b3c66f8a5f`

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

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)

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:

// Express.js example
app.post('/webhooks/dakota', (req, res) => {
  const event = req.body;
  
  // Verify webhook signature (required for security)
  const isValid = verifyWebhookSignature(
    req.headers['x-webhook-signature'],
    req.headers['x-webhook-timestamp'],
    JSON.stringify(req.body),
    process.env.DAKOTA_WEBHOOK_PUBLIC_KEY
  );
  
  if (!isValid) {
    console.error('Webhook signature verification failed');
    return res.status(401).send('Unauthorized');
  }
  
  // Process the event
  handleWebhookEvent(event);
  
  // Respond with 200 to acknowledge receipt
  res.status(200).send('OK');
});

# Flask example
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/dakota', methods=['POST'])
def handle_webhook():
    event = request.get_json()
    
    # Verify webhook signature (required for security)
    signature = request.headers.get('X-Webhook-Signature')
    timestamp = request.headers.get('X-Webhook-Timestamp')
    is_valid = verify_webhook_signature(
        signature,
        timestamp,
        request.get_data(as_text=True),
        os.getenv('DAKOTA_WEBHOOK_PUBLIC_KEY')
    )
    
    if not is_valid:
        print('Webhook signature verification failed')
        return jsonify({'error': 'Unauthorized'}), 401
    
    # Process the event
    handle_webhook_event(event)
    
    # Respond with 200 to acknowledge receipt
    return jsonify({'status': 'ok'}), 200

package main

import (
    "encoding/json"
    "io"
    "log"
    "net/http"
    "os"
)

func webhookHandler(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
        return
    }
    
    // Read request body
    body, err := io.ReadAll(r.Body)
    if err != nil {
        log.Printf("Failed to read request body: %v", err)
        http.Error(w, "Bad request", http.StatusBadRequest)
        return
    }
    defer r.Body.Close()
    
    signature := r.Header.Get("X-Webhook-Signature")
    timestamp := r.Header.Get("X-Webhook-Timestamp")
    
    // Verify webhook signature (required for security)
    isValid := verifyWebhookSignature(
        signature,
        timestamp,
        string(body),
        os.Getenv("DAKOTA_WEBHOOK_PUBLIC_KEY")
    )
    
    if !isValid {
        log.Println("Webhook signature verification failed")
        http.Error(w, "Unauthorized", http.StatusUnauthorized)
        return
    }
    
    // Parse webhook event
    var event map[string]interface{}
    if err := json.Unmarshal(body, &event); err != nil {
        log.Printf("Failed to parse webhook event: %v", err)
        http.Error(w, "Bad request", http.StatusBadRequest)
        return
    }
    
    // Process the event
    handleWebhookEvent(event)
    
    // Respond with 200 to acknowledge receipt
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("OK"))
}

func main() {
    http.HandleFunc("/webhooks/dakota", webhookHandler)
    log.Fatal(http.ListenAndServe(":3000", nil))
}

use axum::{extract::Request, response::Json, http::StatusCode};
use serde_json::Value;
use std::env;

async fn webhook_handler(req: Request) -> Result<StatusCode, (StatusCode, &'static str)> {
    // Extract headers and body
    let signature = req.headers()
        .get("X-Webhook-Signature")
        .and_then(|h| h.to_str().ok())
        .ok_or((StatusCode::BAD_REQUEST, "Missing signature header"))?;
    
    let timestamp = req.headers()
        .get("X-Webhook-Timestamp")
        .and_then(|h| h.to_str().ok())
        .ok_or((StatusCode::BAD_REQUEST, "Missing timestamp header"))?;
    
    let body = axum::body::to_bytes(req.into_body(), usize::MAX)
        .await
        .map_err(|_| (StatusCode::BAD_REQUEST, "Failed to read body"))?;
    
    let body_str = String::from_utf8(body.to_vec())
        .map_err(|_| (StatusCode::BAD_REQUEST, "Invalid UTF-8 in body"))?;
    
    // Verify webhook signature (required for security)
    let public_key = env::var("DAKOTA_WEBHOOK_PUBLIC_KEY")
        .map_err(|_| (StatusCode::INTERNAL_SERVER_ERROR, "Missing public key"))?;
    
    let is_valid = verify_webhook_signature(signature, timestamp, &body_str, &public_key)
        .map_err(|_| (StatusCode::UNAUTHORIZED, "Signature verification failed"))?;
    
    if !is_valid {
        return Err((StatusCode::UNAUTHORIZED, "Invalid signature"));
    }
    
    // Parse webhook event
    let event: Value = serde_json::from_str(&body_str)
        .map_err(|_| (StatusCode::BAD_REQUEST, "Invalid JSON"))?;
    
    // Process the event
    handle_webhook_event(event)
        .await
        .map_err(|_| (StatusCode::INTERNAL_SERVER_ERROR, "Failed to process event"))?;
    
    Ok(StatusCode::OK)
}

import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;
import org.springframework.http.HttpStatus;
import jakarta.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.util.Map;

@RestController
public class WebhookController {
    
    @PostMapping("/webhooks/dakota")
    public ResponseEntity<String> handleWebhook(
            @RequestBody Map<String, Object> event,
            HttpServletRequest request) throws IOException {
        
        String signature = request.getHeader("X-Webhook-Signature");
        String timestamp = request.getHeader("X-Webhook-Timestamp");
        
        // Get raw body for signature verification
        String rawBody = objectMapper.writeValueAsString(event);
        
        // Verify webhook signature (required for security)
        String publicKey = System.getenv("DAKOTA_WEBHOOK_PUBLIC_KEY");
        boolean isValid = verifyWebhookSignature(signature, timestamp, rawBody, publicKey);
        
        if (!isValid) {
            System.err.println("Webhook signature verification failed");
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("Unauthorized");
        }
        
        // Process the event
        handleWebhookEvent(event);
        
        // Respond with 200 to acknowledge receipt
        return ResponseEntity.ok("OK");
    }
    
    private void handleWebhookEvent(Map<String, Object> event) {
        // Your event processing logic here
    }
    
    private boolean verifyWebhookSignature(String signature, String timestamp, 
                                          String body, String publicKey) {
        // Signature verification implementation
        return true; // Placeholder
    }
}

2. Register Your Webhook

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.created", "customer.kyb_status.updated"]`

event_types is an exact-match delivery filter. With global: false, Dakota delivers only the event types you list. An event whose type is absent from the list is never delivered and never retried — it is not queued for your target at all, so there is nothing to redeliver later. List every type you consume, and add a new type to the list before you rely on it. Set global: true to receive every event type for your client; event_types is then ignored.

cURL

curl -X POST https://api.platform.dakota.xyz/webhooks/targets \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/dakota",
    "global": false,
    "event_types": ["transaction.auto.updated", "customer.kyb_status.created", "customer.kyb_status.updated"]
  }'

Response:

{
  "data": {
    "id": "wh_1234567890",
    "url": "https://your-app.com/webhooks/dakota",
    "global": false,
    "event_types": ["transaction.auto.updated", "customer.kyb_status.created", "customer.kyb_status.updated"],
    "created_at": "2024-01-15T10:30:00Z"
  }
}

const response = await fetch('https://api.platform.dakota.xyz/webhooks/targets', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://your-app.com/webhooks/dakota',
    global: false,
    event_types: ['transaction.auto.updated', 'customer.kyb_status.created', 'customer.kyb_status.updated']
  })
});

const webhook = await response.json();
console.log('Created webhook target:', webhook.data.id);

import requests
import uuid

response = requests.post(
    'https://api.platform.dakota.xyz/webhooks/targets',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={
        'url': 'https://your-app.com/webhooks/dakota',
        'global': False,
        'event_types': ['transaction.auto.updated', 'customer.kyb_status.created', 'customer.kyb_status.updated']
    }
)

webhook = response.json()
print(f'Created webhook target: {webhook["data"]["id"]}')

package main

import (
    "bytes"
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{
        "url": "https://your-app.com/webhooks/dakota",
        "global": false,
        "event_types": ["transaction.auto.updated", "customer.kyb_status.created", "customer.kyb_status.updated"]
    }`)
    
    req, _ := http.NewRequest("POST", "https://api.platform.dakota.xyz/webhooks/targets", body)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
    
    let body = json!({
        "url": "https://your-app.com/webhooks/dakota",
        "global": false,
        "event_types": ["transaction.auto.updated", "customer.kyb_status.created", "customer.kyb_status.updated"]
    });
    
    let response = client
        .post("https://api.platform.dakota.xyz/webhooks/targets")
        .headers(headers)
        .json(&body)
        .send()
        .await?;
    
    Ok(())
}

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaWebhookExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = """
            {
              "url": "https://your-app.com/webhooks/dakota",
              "global": false,
              "event_types": ["transaction.auto.updated", "customer.kyb_status.created", "customer.kyb_status.updated"]
            }
            """;
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/webhooks/targets"))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Webhook Events

The envelope schema defines data.previous_attributes and a top-level metadata object, and the API reference lists both as optional. In practice no event populates either today — they are absent from every delivered payload. Drive your state machine off data.object alone; do not write change-detection logic that depends on previous_attributes being present.

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.

Status progression

The data.object.status field on transaction webhooks progresses through the following observable values. Inspect this field on every *.updated event to drive your own state machine — there is no separate “status rank” or priority concept beyond this order.

Order	Status	Meaning
1	`pending`	Transaction created; not yet acted on. Fires on `.created` and the first `.updated`.
2	`processing`	Dakota is actively moving funds (conversion, on-chain broadcast, or bank submission).
3a	`completed`	Terminal success. `completed_at` is set.
3b	`failed`	Terminal failure. Inspect `data.object.failure_reason` (when present) for cause.

A transaction only ever moves forward through this sequence — statuses never regress. Treat completed and failed as terminal; no further *.updated events fire after either. Additional internal statuses (for example, awaiting_confirmation, broadcasted, pending_return) may appear on the underlying transaction object but are not surfaced as distinct webhook lifecycle stages.

Fee fields in the receipt

The data.object.receipt object breaks the transaction’s fees into separate fields. The same receipt shape is returned by GET /transactions/{transaction_id}.

Field	Meaning
`external_fee`	Fees charged by parties outside Dakota, such as banking partners. Currently reported as zero for bank transfers. For international (SWIFT) wires, intermediary and beneficiary banks can deduct fees en route; Dakota does not learn those deductions and they do not appear here — the amount received can be lower than the amount sent.
`dakota_fee`	Dakota’s own fee.
`client_fee`	Your developer fee, charged per the `developer_fee_bps` set on the account or one-off transaction.
`gas_fee`	Gas fees for the blockchain leg of the transaction.

developer_fee_bps is write-only: it is accepted on account create, account update, and one-off transaction create, but is not returned by GET /accounts/{account_id} or transaction reads. Record the value you set, and verify the fee actually charged via client_fee on each receipt. Updating developer_fee_bps with PUT /accounts/{account_id} applies to future transactions only.

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.

{
  "id": "2tQRvU7tHKLBcd3qXrPp4jYsKXm",
  "type": "transaction.auto.created",
  "created": 1737457500,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "id": "2tQRvvnYkN6edEJUTmF1LzTj2ug",
      "auto_account_id": "2tQRvK9pRzM4nVbW8sHqL5jXmYt",
      "destination_id": "2tQRvD3xFcJ7bKpW9qNsT4hZmYr",
      "type": "onramp",
      "status": "pending",
      "created_at": 1737457500,
      "updated_at": 1737457500,
      "receipt": {
        "input_currency": "USD",
        "output_currency": "USDC",
        "initial_amount": "1000.00",
        "subtotal_amount": "999.00",
        "converted_amount": "999.00",
        "outgoing_amount": "999.00",
        "external_fee": "1.00",
        "client_fee": "0.00",
        "dakota_fee": "0.00",
        "exchange_rate": "1.00"
      },
      "crypto_details": {
        "destination_network_id": "ethereum",
        "destination_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1"
      },
      "sender_details": {
        "sender_type": "individual",
        "sender_account_holder_name": "Jane Doe",
        "sender_bank_name": "Example Bank",
        "sender_routing_number": "021000021",
        "sender_account_number": "123456789",
        "sender_account_type": "checking"
      }
    }
  }
}

transaction.auto.updated — emitted on every status change or detail update (inspect data.object.status to distinguish processing, completed, failed).

{
  "id": "2tQRvB8mTpYxZ4nWgK6sLvHqRdJ",
  "type": "transaction.auto.updated",
  "created": 1737457620,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "id": "2tQRvvnYkN6edEJUTmF1LzTj2ug",
      "auto_account_id": "2tQRvK9pRzM4nVbW8sHqL5jXmYt",
      "destination_id": "2tQRvD3xFcJ7bKpW9qNsT4hZmYr",
      "type": "onramp",
      "status": "completed",
      "created_at": 1737457500,
      "updated_at": 1737457620,
      "completed_at": 1737457620,
      "receipt": {
        "input_currency": "USD",
        "output_currency": "USDC",
        "initial_amount": "1000.00",
        "subtotal_amount": "999.00",
        "converted_amount": "999.00",
        "outgoing_amount": "999.00",
        "external_fee": "1.00",
        "client_fee": "0.00",
        "dakota_fee": "0.00",
        "exchange_rate": "1.00"
      },
      "crypto_details": {
        "destination_network_id": "ethereum",
        "destination_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1",
        "tx_hash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456"
      },
      "sender_details": {
        "sender_type": "individual",
        "sender_account_holder_name": "Jane Doe",
        "sender_bank_name": "Example Bank",
        "sender_routing_number": "021000021",
        "sender_account_number": "123456789",
        "sender_account_type": "checking"
      }
    }
  }
}

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. data.object carries a one-off transaction snapshot — the abbreviated { id, customer_id, status } object shown in some list examples is just an example view, not a smaller payload. It is close to the response body of GET /transactions/{transaction_id} but not field-for-field identical — several keys are spelled differently on the event:

On `GET /transactions/{id}`	On the event
`crypto_address`	`temporary_address`
`receipt.input` / `receipt.output` (objects)	`receipt.initial_amount` / `receipt.outgoing_amount` (strings)
`crypto_details.deposit_transaction_hash`	`crypto_details.deposit_tx_hash`
`crypto_details.source_crypto_address`	`crypto_details.source_address`

resource_type and destination_payment_rail are not emitted on the event at all. Fields that carry no value are omitted rather than sent as null. The example below illustrates the shape; log a delivered payload and code against what you actually receive.

{
  "id": "2tQRvL9pRzM4nVbW8sHqL5jXmYt",
  "type": "transaction.one_off.updated",
  "created": 1737457620,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "id": "2LfZn6LNoSvMGuSQ0pLLof1OneA",
      "resource_type": "one_off",
      "customer_id": "2LfTd6QQrUyPKwRR9qMMyk7CMHS",
      "status": "completed",
      "crypto_address": "0xabc...",
      "source_network_id": "ethereum-mainnet",
      "source_asset": "USDC",
      "destination_id": "2LfYm5KMnRvLFtRP7nJJug4zBAN",
      "destination_asset": "USD",
      "amount": "1250.00",
      "payment_reference": "INV 2024 042",
      "destination_payment_rail": "ach",
      "receipt": {
        "input_currency": "USDC",
        "output_currency": "USD",
        "initial_amount": "1250.00",
        "subtotal_amount": "1250.00",
        "converted_amount": "1250.00",
        "outgoing_amount": "1249.00",
        "external_fee": "1.00",
        "client_fee": "0.00",
        "dakota_fee": "0.00",
        "exchange_rate": "1.00"
      },
      "crypto_details": {
        "deposit_transaction_hash": "0xabc123def456789012345678901234567890abcdef1234567890abcdef123456"
      },
      "created_at": 1737457500,
      "updated_at": 1737457620,
      "completed_at": 1737457620
    }
  }
}

For the full field set — including return and reversal fields on failed/returned/reversed one-offs — see the OneOffTransaction schema on GET /transactions/{transaction_id} and the One-off transaction lifecycle.

Customer Events

customer.kyb_status.created — emitted once per customer, when Dakota first records a KYB status for that customer. kyb_status carries whatever status Dakota records first: approved for a customer that provisioning approves, or auto_declined for an application that is auto-declined. Every later change to that status arrives as customer.kyb_status.updated.

{
  "id": "31Tgw2Yw8bXqA5cV9nK3jLpRtS",
  "type": "customer.kyb_status.created",
  "created": 1737457500,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "customer_id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
      "kyb_status": "approved"
    }
  }
}

Subscribe to customer.kyb_status.created as well as customer.kyb_status.updated. A target that lists only customer.kyb_status.updated never learns the customer’s first KYB status, because event_types is an exact-match filter. Unlike customer.kyb_status.updated, this event never carries a reason_code. customer.kyb_status.updated

{
  "id": "31Tgw5Rk4pQmZ8dV2nT7hLxWbYc",
  "type": "customer.kyb_status.updated",
  "created": 1737457560,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "customer_id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
      "kyb_status": "approved"
    }
  }
}

Some customer.kyb_status.updated events carry an additional reason_code that explains why the status changed. It is present only on transitions that have a defined reason; on all other status updates it is absent.

`reason_code` value	Fires when
`pending_proof_of_address`	The customer is frozen because their rolling 7-day inbound volume crossed the $3,000 threshold and no PoA is on file.
`proof_of_address_rejected`	Compliance rejected a submitted PoA document.
`proof_of_address_approved`	Compliance approved a submitted PoA, unfreezing the customer.
`sanctions_hit`	Sanctions screening — name screening or blockchain address screening — returned a confirmed hit and the customer was frozen.
`sanctions_cleared`	A compliance freeze was lifted and the customer’s pre-freeze KYB status restored. Emitted for any non-PoA unfreeze, not only for a cleared sanctions hit — do not treat it as proof the customer was ever sanctioned.
`compliance_hold`	The customer was frozen for a compliance reason that is not a confirmed sanctions match — either a manual reviewer hold, or an automated risk hit in a non-sanctions category (for example mixer or stolen-funds exposure).

Example payload with reason_code:

{
  "id": "31Tgw7Np6sVdY4cX9mK2gLtRfHq",
  "type": "customer.kyb_status.updated",
  "created": 1737457620,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "customer_id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
      "kyb_status": "frozen",
      "reason_code": "pending_proof_of_address"
    }
  }
}

customer.created

{
  "id": "31Tgw9Xt2mBvA6dW5nQ8hLpRcKj",
  "type": "customer.created",
  "created": 1737457500,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "customer_id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
      "name": "Jane Doe",
      "type": "individual",
      "external_id": "your-internal-id-42"
    }
  }
}

external_id is present only when you set one for the customer. customer.updated — defined and subscribable, but no Dakota flow currently emits it. Do not build on it. The customer changes Dakota does deliver today are KYB status (customer.kyb_status.created / customer.kyb_status.updated), capability standing (customer.capability_status.updated), and deletion (customer.deleted, below). Changes to a customer’s name or email — which Dakota may apply itself during KYB provisioning — are not surfaced on any webhook; re-read GET /customers/{customer_id} if you need them. customer.deleted

{
  "id": "31TgwFt8xPkL4mB2qY6nZdReVhC",
  "type": "customer.deleted",
  "created": 1737457620,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "customer_id": "31TgvufZK3gDXBcA3BnSeLWiSn7"
    }
  }
}

customer.deleted is delivered to targets subscribed to all events (global: true), but it is not yet in the public EventType enum, so it cannot be named in an event_types filter today.

Token-sharing imports carry import_reference. For a customer created via a token-sharing import (Persona, Sumsub), the customer.created payload includes data.object.import_reference, a { source, reference } object where reference is the token you submitted for that import (for Persona, the cnst_... share token). Use it to tie the event back to the source record you minted the token from, with no extra lookup:

{
  "id": "31Tgw9Xt2mBvA6dW5nQ8hLpRcKj",
  "type": "customer.created",
  "created": 1737457500,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "customer_id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
      "name": "Jane Doe",
      "type": "individual",
      "import_reference": {
        "source": "persona",
        "reference": "cnst_YourSubmittedShareToken"
      }
    }
  }
}

Notes:

source tells you which import produced the customer (persona, sumsub), so you branch on one field rather than a per-vendor key.
We cannot include your source Inquiry id itself: Persona does not share it with Dakota as the destination organization. The token you submitted is the reliable correlation key.
import_reference is a correlation hint, not a primary key: in rare import-retry cases the same reference can appear on more than one customer.created. If you would rather not track tokens at all, the import job maps every token to its result: GET /customers/persona-import-jobs/{job_id} returns each token alongside its customer_id and application_id.

Apart from import_reference on token-sharing imports, the payload carries no other provider-side metadata (no Persona Inquiry IDs, no Sumsub applicant IDs). To resolve a Dakota customer back to a provider identifier, either:

Look it up on the imported application. GET /customers/{customer_id} returns application_id; GET /applications/{application_id} exposes provider (persona or sumsub) and provider_applicant_id (the Persona inquiry ID or Sumsub applicant ID). See Persona Token Import and Sumsub Token Import.
For Persona imports, correlate through the import job. GET /customers/persona-import-jobs/{job_id} returns each redeemed token with its customer_id and application_id, so you can map the token you originally submitted back to a Dakota customer without keeping a separate table.

customer.kyb_application.submitted

{
  "id": "31TgwBZq7nCvD8eX3mR5gLtWpFk",
  "type": "customer.kyb_application.submitted",
  "created": 1737457500,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "customer_id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
      "application_id": "31TgwCp3sMdF9gY4nT6hKvXqRbLm",
      "application_type": "business"
    }
  }
}

Request for Information (RFI) Events

During review, compliance may need more information about a customer you onboarded. The application stays open and that customer stays blocked until the information arrives. You own the relationship with your customer. Dakota never contacts them. These events are how you learn a customer is blocked and what is still owed, so you can collect it in your own product. customer.rfi.requested — a reviewer opened a request. requirements lists everything the customer must supply.

{
  "id": "31Tgw8Lm2nPqR7dV4jK9hTxWbZc",
  "type": "customer.rfi.requested",
  "created": 1737457800,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "customer_id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
      "application_id": "31TgwCp3sMdF9gY4nT6hKvXqRbLm",
      "message_id": "rfimsg_31TgwHk4mN8pQ2rV5jL9dXtZbYc",
      "requested_at": 1737457800,
      "requirements": [
        {
          "type": "document",
          "document_type": "bank_statement",
          "entity": { "kind": "business" },
          "status": "missing"
        },
        {
          "type": "document",
          "purpose": "individual_proof_of_address",
          "entity": { "kind": "individual", "id": "31TgwF7hK2mQ8dR5nV3jLpXtSbY" },
          "status": "missing"
        },
        { "type": "field", "path": "business.business_description" },
        { "type": "question", "key": "q1", "prompt": "Explain the source of the June deposits.", "require_document": true }
      ]
    }
  }
}

customer.rfi.responded — the information arrived and the application is back with a reviewer. Stop chasing the customer.

{
  "id": "31TgwA3pN6kRt9fW2mL8jQxYcBd",
  "type": "customer.rfi.responded",
  "created": 1737544200,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "customer_id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
      "application_id": "31TgwCp3sMdF9gY4nT6hKvXqRbLm",
      "responded_at": 1737544200
    }
  }
}

customer.application.withdrawn — the application was withdrawn, either by the applicant or by you. Withdrawal is final.

{
  "id": "31TgwB9qP4mSt8gX3nK7jRyZdCe",
  "type": "customer.application.withdrawn",
  "created": 1737630600,
  "api_version": "1.0.0",
  "data": {
    "object": {
      "customer_id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
      "application_id": "31TgwCp3sMdF9gY4nT6hKvXqRbLm",
      "reason": "Customer opted not to proceed"
    }
  }
}

Reading `requirements`

Each entry is one thing the customer must supply.

`type`	Meaning	Fields
`document`	A document must be supplied	`document_type` or `purpose`, plus `entity` and `status`
`field`	An application field must be corrected	`path`
`question`	A reviewer asked a free-text question	`key`, `prompt`, `require_document`

A document requirement names what is needed in exactly one of two ways, never both:

document_type — a specific kind of document, e.g. bank_statement. Supply that document.
purpose — a compliance requirement that several document types could satisfy, e.g. business_proof_of_address. Let your customer choose among the documents that satisfy it, rather than demanding one specific type.

Switch on whichever field is present. A value from one vocabulary never appears in the other field. entity says who a document belongs to: {"kind": "business"} for the business, {"kind": "individual", "id": "..."} for a named individual, or {"kind": "edd"} for enhanced due diligence. status is missing when nothing is on file for the requirement, and on_file when a document is already there and the reviewer is asking for it again — send a replacement. Answer every question. A resubmission that carries documents but leaves questions unanswered goes back to a reviewer who still cannot act on it. When require_document is true the answer must also carry an upload; a text-only answer leaves the request open. status is scoped to the party in entity. A beneficial owner having supplied a proof of address does not make the business’s proof of address on_file. message_id identifies the request. Use it to deduplicate redeliveries and to pair a later customer.rfi.responded with the request it answers. requirements is always present and always an array. It is empty when a reviewer sent a plain request with no machine-readable scope; the request is still open and still needs a response.

Where to get the resubmission link

The event does not contain the resubmission link. Fetch it from the customer:

curl https://api.dakota.xyz/customers/31TgvufZK3gDXBcA3BnSeLWiSn7 \
  -H "X-API-Key: $DAKOTA_API_KEY"

{
  "id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
  "status": "info_requested",
  "application_url": "https://onboarding.dakota.xyz/applications/31TgwCp3sMdF9gY4nT6hKvXqRbLm?token=…",
  "resubmit_url": "https://onboarding.dakota.xyz/applications/31TgwCp3sMdF9gY4nT6hKvXqRbLm/resubmit?token=…",
  "rfi": { "last_sent_at": 1737457800, "times_sent": 1 }
}

resubmit_url is present only while a request is open (status is info_requested). It opens a Dakota-hosted page that lists the same requirements and accepts uploads and answers. Forward it to your customer and the request closes when they submit.

resubmit_url contains an access token. Anyone holding it can open that application. Treat it like a password-reset link: send it to your customer, do not post it in a shared channel, and do not log it.This is exactly why it is not in the webhook body. A webhook body comes to rest in your application logs, APM traces, proxy logs, dead-letter queues and retry buffers, and delivery is retried, so one event can land in several of them. Identifiers like customer_id are harmless there. A credential is not. Fetching the link over your own authenticated request keeps it out of all of those, and keeps webhook bodies safe to log in full while debugging.

Resolving a request

Withdraw when the customer will not or cannot continue:

curl -X POST \
  https://api.dakota.xyz/customers/31TgvufZK3gDXBcA3BnSeLWiSn7/applications/31TgwCp3sMdF9gY4nT6hKvXqRbLm/withdraw \
  -H "X-API-Key: $DAKOTA_API_KEY" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Customer opted not to proceed"}'

reason is optional and is recorded for audit. Withdrawal is final: the customer’s status becomes withdrawn, and onboarding them later requires a new application. An application that already has a decision returns 409.

Handling the events

app.post('/webhooks/dakota', async (req, res) => {
  // Verify the signature first — see Webhook Signature Verification above.
  const event = req.body;

  switch (event.type) {
    case 'customer.rfi.requested': {
      const { customer_id, application_id, requirements } = event.data.object;

      const documents = requirements.filter((r) => r.type === 'document');
      const questions = requirements.filter((r) => r.type === 'question');

      // The link is NOT in the event. Fetch it when you need it.
      const customer = await dakota.get(`/customers/${customer_id}`);

      await notifyOurCustomer(customer_id, {
        // Exactly one of document_type / purpose is set on each entry.
        needs: documents.map((d) => d.document_type ?? d.purpose),
        questions: questions.map((q) => q.prompt),
        link: customer.resubmit_url,
      });
      break;
    }

    case 'customer.rfi.responded':
      await stopChasing(event.data.object.customer_id);
      break;

    case 'customer.application.withdrawn':
      await closeOut(event.data.object.customer_id, event.data.object.reason);
      break;
  }

  res.sendStatus(200);
});

An RFI ends in a decision, not in a separate event. Keep handling customer.kyb_status.updated for the approval or decline. Do not treat “we sent the link” as resolution. The request stays open, and reviewers see nothing, until the customer actually responds. Drive any follow-up you do from customer.rfi.responded.

Application status changes that do not emit a webhook

declined transitions driven by KYC/KYB rejection do not emit their own application event; they arrive as customer.kyb_status.updated. If you need to track a state that has no event of its own, poll GET /applications/{application_id} and inspect application_status.

Verification Code Examples

Ed25519 verification implementations — pick your language. See the public keys and required headers in Webhook Signature Verification above.

const crypto = require('crypto');
const { Buffer } = require('buffer');

function verifyWebhookSignature(signature, timestamp, payload, dakotaPublicKeyHex) {
  if (!signature || !timestamp || !payload || !dakotaPublicKeyHex) {
    console.error('Missing required parameters for signature verification');
    return false;
  }

  // Check timestamp to prevent replay attacks (within 5 minutes)
  const currentTime = Math.floor(Date.now() / 1000);
  const webhookTime = parseInt(timestamp);
  const timeDifference = Math.abs(currentTime - webhookTime);
  
  if (timeDifference > 300) { // 5 minutes
    console.error('Webhook timestamp too old or too far in future');
    return false;
  }

  // Create the signed payload (timestamp + body)
  const signedPayload = timestamp + payload;
  
  try {
    // Decode the public key from hex and signature from base64
    const publicKeyBuffer = Buffer.from(dakotaPublicKeyHex, 'hex');
    const signatureBuffer = Buffer.from(signature, 'base64');
    
    // Validate key length (Ed25519 public key should be 32 bytes)
    if (publicKeyBuffer.length !== 32) {
      console.error('Invalid Ed25519 public key length:', publicKeyBuffer.length);
      return false;
    }
    
    // Wrap raw Ed25519 key in DER format for Node.js crypto API
    const derPrefix = Buffer.from([
      0x30, 0x2A, // SEQUENCE, 42 bytes
      0x30, 0x05, // SEQUENCE, 5 bytes
      0x06, 0x03, 0x2B, 0x65, 0x70, // OID 1.3.101.112 (Ed25519)
      0x03, 0x21, 0x00 // BIT STRING, 33 bytes (including unused bits byte)
    ]);
    const derKey = Buffer.concat([derPrefix, publicKeyBuffer]);
    
    const publicKey = crypto.createPublicKey({
      key: derKey,
      format: 'der',
      type: 'spki'
    });
    
    // Verify the signature using Ed25519
    const isValid = crypto.verify(
      null, // Ed25519 doesn't use a digest algorithm
      Buffer.from(signedPayload, 'utf8'),
      publicKey,
      signatureBuffer
    );
    
    return isValid;
  } catch (error) {
    console.error('Signature verification failed:', error);
    return false;
  }
}

// Complete Express.js webhook handler example
const express = require('express');
const app = express();

// Middleware to capture raw body for signature verification
app.use('/webhooks/dakota', express.raw({ type: 'application/json' }));

app.post('/webhooks/dakota', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const rawBody = req.body.toString('utf8');
  
  // Verify webhook signature
  const isValid = verifyWebhookSignature(
    signature,
    timestamp,
    rawBody,
    process.env.DAKOTA_WEBHOOK_PUBLIC_KEY
  );
  
  if (!isValid) {
    console.error('Webhook signature verification failed');
    return res.status(401).send('Unauthorized');
  }
  
  try {
    const event = JSON.parse(rawBody);
    console.log('Received verified webhook:', event.type, event.id);
    
    // Process the event
    handleWebhookEvent(event);
    
    // Respond with 200 to acknowledge receipt
    res.status(200).send('OK');
  } catch (error) {
    console.error('Error processing webhook:', error);
    res.status(400).send('Bad Request');
  }
});

function handleWebhookEvent(event) {
  // Make processing idempotent
  if (isEventAlreadyProcessed(event.id)) {
    console.log('Event already processed:', event.id);
    return;
  }
  
  switch (event.type) {
    case 'transaction.auto.updated':
      handleTransactionUpdate(event.data);
      break;
    case 'customer.kyb_status.created':
    case 'customer.kyb_status.updated':
      handleCustomerUpdate(event.data);
      break;
    default:
      console.log(`Unknown event type: ${event.type}`);
  }
  
  // Mark as processed
  markEventAsProcessed(event.id);
}

function isEventAlreadyProcessed(eventId) {
  // Check your database/cache for this event ID
  // Return true if already processed
  return false;
}

function markEventAsProcessed(eventId) {
  // Store the event ID in your database/cache
  console.log('Marking event as processed:', eventId);
}

function handleTransactionUpdate(data) {
  const obj = data.object || {};
  console.log('Processing transaction update:', obj.id, obj.status);
  // Your transaction handling logic here
}

function handleCustomerUpdate(data) {
  const obj = data.object || {};
  console.log('Processing customer update:', obj.customer_id, obj.kyb_status);
  // Your customer handling logic here
}

import base64
import json
import time
import os
from flask import Flask, request, jsonify
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
from cryptography.exceptions import InvalidSignature

def verify_webhook_signature(signature, timestamp, body, dakota_public_key_hex):
    if not all([signature, timestamp, body, dakota_public_key_hex]):
        print('Missing required parameters for signature verification')
        return False
    
    try:
        # Check timestamp to prevent replay attacks (within 5 minutes)
        current_time = int(time.time())
        webhook_time = int(timestamp)
        time_difference = abs(current_time - webhook_time)
        
        if time_difference > 300:  # 5 minutes
            print('Webhook timestamp too old or too far in future')
            return False
        
        # Create the signed payload (timestamp + body)
        signed_payload = timestamp + body
        
        # Decode the public key from hex and signature from base64
        public_key_bytes = bytes.fromhex(dakota_public_key_hex)
        signature_bytes = base64.b64decode(signature)
        
        # Validate key length (Ed25519 public key should be 32 bytes)
        if len(public_key_bytes) != 32:
            print(f'Invalid Ed25519 public key length: {len(public_key_bytes)}')
            return False
        
        # Create Ed25519 public key object
        public_key = Ed25519PublicKey.from_public_bytes(public_key_bytes)
        
        # Verify the signature
        public_key.verify(signature_bytes, signed_payload.encode('utf-8'))
        return True
    except (InvalidSignature, ValueError, Exception) as e:
        print(f'Signature verification failed: {e}')
        return False

# Complete Flask webhook handler example
app = Flask(__name__)
processed_events = set()  # Simple in-memory store (use database in production)

@app.route('/webhooks/dakota', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')
    timestamp = request.headers.get('X-Webhook-Timestamp')
    raw_body = request.get_data(as_text=True)
    
    # Verify webhook signature
    is_valid = verify_webhook_signature(
        signature,
        timestamp,
        raw_body,
        os.getenv('DAKOTA_WEBHOOK_PUBLIC_KEY')
    )
    
    if not is_valid:
        print('Webhook signature verification failed')
        return jsonify({'error': 'Unauthorized'}), 401
    
    try:
        event = json.loads(raw_body)
        print(f'Received verified webhook: {event.get("type")} {event.get("id")}')
        
        # Process the event
        handle_webhook_event(event)
        
        # Respond with 200 to acknowledge receipt
        return jsonify({'status': 'ok'}), 200
    except (json.JSONDecodeError, KeyError) as e:
        print(f'Error processing webhook: {e}')
        return jsonify({'error': 'Bad Request'}), 400

def handle_webhook_event(event):
    event_id = event.get('id')
    
    # Make processing idempotent
    if is_event_already_processed(event_id):
        print(f'Event already processed: {event_id}')
        return
    
    event_type = event.get('type')
    event_data = event.get('data', {})
    
    if event_type == 'transaction.auto.updated':
        handle_transaction_update(event_data)
    elif event_type in ('customer.kyb_status.created', 'customer.kyb_status.updated'):
        handle_customer_update(event_data)
    else:
        print(f'Unknown event type: {event_type}')
    
    # Mark as processed
    mark_event_as_processed(event_id)

def is_event_already_processed(event_id):
    # Check your database/cache for this event ID
    return event_id in processed_events

def mark_event_as_processed(event_id):
    # Store the event ID in your database/cache
    processed_events.add(event_id)
    print(f'Marking event as processed: {event_id}')

def handle_transaction_update(data):
    obj = data.get('object', {})
    transaction_id = obj.get('id')
    status = obj.get('status')
    print(f'Processing transaction update: {transaction_id} -> {status}')
    # Your transaction handling logic here

def handle_customer_update(data):
    obj = data.get('object', {})
    customer_id = obj.get('customer_id')
    kyb_status = obj.get('kyb_status')
    print(f'Processing customer update: {customer_id} -> {kyb_status}')
    # Your customer handling logic here

if __name__ == '__main__':
    app.run(port=3000, debug=True)

use ed25519_dalek::{Signature, Verifier, VerifyingKey};
use base64::{Engine as _, engine::general_purpose};
use std::time::{SystemTime, UNIX_EPOCH};
use warp::Filter;
use serde_json::{Value, json};
use std::collections::HashSet;
use std::sync::{Arc, Mutex};
use std::convert::Infallible;

#[derive(Debug)]
pub struct WebhookVerifier {
    public_key: VerifyingKey,
    processed_events: Arc<Mutex<HashSet<String>>>,
}

impl WebhookVerifier {
    pub fn new(public_key_hex: &str) -> Result<Self, Box<dyn std::error::Error>> {
        let public_key_bytes = hex::decode(public_key_hex)?;
        
        // Validate key length (Ed25519 public key should be 32 bytes)
        if public_key_bytes.len() != 32 {
            return Err(format!("Invalid Ed25519 public key length: {}", public_key_bytes.len()).into());
        }
        
        let public_key = VerifyingKey::from_bytes(
            &public_key_bytes.try_into().map_err(|_| "Invalid key length")?
        )?;
        
        Ok(Self {
            public_key,
            processed_events: Arc::new(Mutex::new(HashSet::new())),
        })
    }
    
    pub fn verify_signature(&self, signature: &str, timestamp: &str, body: &str) -> Result<bool, Box<dyn std::error::Error>> {
        if signature.is_empty() || timestamp.is_empty() || body.is_empty() {
            println!("Missing required parameters for signature verification");
            return Ok(false);
        }
        
        // Check timestamp to prevent replay attacks (within 5 minutes)
        let current_time = SystemTime::now()
            .duration_since(UNIX_EPOCH)?
            .as_secs();
        let webhook_time: u64 = timestamp.parse()?;
        let time_difference = (current_time as i64 - webhook_time as i64).abs();
        
        if time_difference > 300 {
            println!("Webhook timestamp too old or too far in future");
            return Ok(false);
        }
        
        // Create the signed payload (timestamp + body)
        let signed_payload = format!("{}{}", timestamp, body);
        
        // Decode signature
        let signature_bytes = general_purpose::STANDARD.decode(signature)?;
        let signature = Signature::from_bytes(&signature_bytes.try_into().map_err(|_| "Invalid signature length")?);
        
        // Verify signature
        match self.public_key.verify(signed_payload.as_bytes(), &signature) {
            Ok(_) => Ok(true),
            Err(e) => {
                println!("Signature verification failed: {}", e);
                Ok(false)
            }
        }
    }
    
    pub fn is_event_processed(&self, event_id: &str) -> bool {
        self.processed_events.lock().unwrap().contains(event_id)
    }
    
    pub fn mark_event_processed(&self, event_id: &str) {
        self.processed_events.lock().unwrap().insert(event_id.to_string());
        println!("Marking event as processed: {}", event_id);
    }
    
    pub fn handle_webhook_event(&self, event: &Value) -> Result<(), Box<dyn std::error::Error>> {
        let event_id = event["id"].as_str().unwrap_or("");
        
        // Make processing idempotent
        if self.is_event_processed(event_id) {
            println!("Event already processed: {}", event_id);
            return Ok(());
        }
        
        let event_type = event["type"].as_str().unwrap_or("");
        let event_data = &event["data"];
        
        match event_type {
            "transaction.auto.updated" => {
                self.handle_transaction_update(event_data)?;
            }
            "customer.kyb_status.created" | "customer.kyb_status.updated" => {
                self.handle_customer_update(event_data)?;
            }
            _ => {
                println!("Unknown event type: {}", event_type);
            }
        }
        
        // Mark as processed
        self.mark_event_processed(event_id);
        Ok(())
    }
    
    fn handle_transaction_update(&self, data: &Value) -> Result<(), Box<dyn std::error::Error>> {
        let obj = &data["object"];
        let transaction_id = obj["id"].as_str().unwrap_or("");
        let status = obj["status"].as_str().unwrap_or("");
        println!("Processing transaction update: {} -> {}", transaction_id, status);
        // Your transaction handling logic here
        Ok(())
    }
    
    fn handle_customer_update(&self, data: &Value) -> Result<(), Box<dyn std::error::Error>> {
        let obj = &data["object"];
        let customer_id = obj["customer_id"].as_str().unwrap_or("");
        let kyb_status = obj["kyb_status"].as_str().unwrap_or("");
        println!("Processing customer update: {} -> {}", customer_id, kyb_status);
        // Your customer handling logic here
        Ok(())
    }
}

// Complete Warp webhook handler example
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let public_key_hex = std::env::var("DAKOTA_WEBHOOK_PUBLIC_KEY")
        .expect("DAKOTA_WEBHOOK_PUBLIC_KEY environment variable is required");
    
    let verifier = Arc::new(WebhookVerifier::new(&public_key_hex)?);
    
    let webhook_route = warp::path("webhooks")
        .and(warp::path("dakota"))
        .and(warp::post())
        .and(warp::header::<String>("x-webhook-signature"))
        .and(warp::header::<String>("x-webhook-timestamp"))
        .and(warp::body::bytes())
        .and_then({
            let verifier = verifier.clone();
            move |signature: String, timestamp: String, body: bytes::Bytes| {
                let verifier = verifier.clone();
                async move {
                    handle_webhook(verifier, signature, timestamp, body).await
                }
            }
        });
    
    let port = std::env::var("PORT")
        .unwrap_or_else(|_| "3000".to_string())
        .parse::<u16>()
        .unwrap_or(3000);
    
    println!("Starting webhook server on port {}", port);
    warp::serve(webhook_route)
        .run(([0, 0, 0, 0], port))
        .await;
    
    Ok(())
}

async fn handle_webhook(
    verifier: Arc<WebhookVerifier>,
    signature: String,
    timestamp: String,
    body: bytes::Bytes,
) -> Result<impl warp::Reply, Infallible> {
    let body_str = match String::from_utf8(body.to_vec()) {
        Ok(s) => s,
        Err(_) => {
            return Ok(warp::reply::with_status(
                "Invalid UTF-8 in body",
                warp::http::StatusCode::BAD_REQUEST,
            ));
        }
    };
    
    // Verify webhook signature
    let is_valid = match verifier.verify_signature(&signature, &timestamp, &body_str) {
        Ok(valid) => valid,
        Err(e) => {
            println!("Signature verification error: {}", e);
            false
        }
    };
    
    if !is_valid {
        println!("Webhook signature verification failed");
        return Ok(warp::reply::with_status(
            "Unauthorized",
            warp::http::StatusCode::UNAUTHORIZED,
        ));
    }
    
    // Parse webhook event
    let event: Value = match serde_json::from_str(&body_str) {
        Ok(e) => e,
        Err(e) => {
            println!("Failed to parse webhook event: {}", e);
            return Ok(warp::reply::with_status(
                "Bad Request",
                warp::http::StatusCode::BAD_REQUEST,
            ));
        }
    };
    
    println!("Received verified webhook: {} {}", 
        event["type"].as_str().unwrap_or("unknown"), 
        event["id"].as_str().unwrap_or("unknown")
    );
    
    // Process the event
    if let Err(e) = verifier.handle_webhook_event(&event) {
        println!("Error processing webhook event: {}", e);
        return Ok(warp::reply::with_status(
            "Internal Server Error",
            warp::http::StatusCode::INTERNAL_SERVER_ERROR,
        ));
    }
    
    Ok(warp::reply::with_status(
        "OK",
        warp::http::StatusCode::OK,
    ))
}

import java.security.*;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
import java.util.Set;
import java.util.concurrent.ConcurrentHashMap;
import java.time.Instant;
import java.nio.charset.StandardCharsets;

import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;
import org.springframework.http.HttpStatus;
import jakarta.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.util.Map;

public class WebhookVerifier {
    private final PublicKey publicKey;
    private final Set<String> processedEvents = ConcurrentHashMap.newKeySet();
    
    public WebhookVerifier(String publicKeyHex) throws Exception {
        byte[] publicKeyBytes = hexToBytes(publicKeyHex);
        
        // Validate key length (Ed25519 public key should be 32 bytes)
        if (publicKeyBytes.length != 32) {
            throw new IllegalArgumentException("Invalid Ed25519 public key length: " + publicKeyBytes.length);
        }
        
        // Raw Ed25519 key - wrap in DER format for Java crypto API
        byte[] derKey = wrapRawKeyInDER(publicKeyBytes);
        X509EncodedKeySpec keySpec = new X509EncodedKeySpec(derKey);
        KeyFactory keyFactory = KeyFactory.getInstance("EdDSA");
        this.publicKey = keyFactory.generatePublic(keySpec);
    }
    
    private byte[] hexToBytes(String hex) {
        int len = hex.length();
        byte[] data = new byte[len / 2];
        for (int i = 0; i < len; i += 2) {
            data[i / 2] = (byte) ((Character.digit(hex.charAt(i), 16) << 4)
                                + Character.digit(hex.charAt(i+1), 16));
        }
        return data;
    }
    
    private byte[] wrapRawKeyInDER(byte[] rawKey) {
        // Ed25519 DER prefix for public key
        byte[] derPrefix = {
            0x30, 0x2A, // SEQUENCE, 42 bytes
            0x30, 0x05, // SEQUENCE, 5 bytes
            0x06, 0x03, 0x2B, 0x65, 0x70, // OID 1.3.101.112 (Ed25519)
            0x03, 0x21, 0x00 // BIT STRING, 33 bytes (including unused bits byte)
        };
        
        byte[] derKey = new byte[derPrefix.length + rawKey.length];
        System.arraycopy(derPrefix, 0, derKey, 0, derPrefix.length);
        System.arraycopy(rawKey, 0, derKey, derPrefix.length, rawKey.length);
        
        return derKey;
    }
    
    public boolean verifySignature(String signature, String timestamp, String body) {
        if (signature == null || timestamp == null || body == null || 
            signature.isEmpty() || timestamp.isEmpty() || body.isEmpty()) {
            System.err.println("Missing required parameters for signature verification");
            return false;
        }
        
        try {
            // Check timestamp to prevent replay attacks (within 5 minutes)
            long currentTime = Instant.now().getEpochSecond();
            long webhookTime = Long.parseLong(timestamp);
            long timeDifference = Math.abs(currentTime - webhookTime);
            
            if (timeDifference > 300) { // 5 minutes
                System.err.println("Webhook timestamp too old or too far in future");
                return false;
            }
            
            // Create the signed payload (timestamp + body)
            String signedPayload = timestamp + body;
            
            // Decode signature
            byte[] signatureBytes = Base64.getDecoder().decode(signature);
            
            // Verify signature using Ed25519
            Signature verifier = Signature.getInstance("EdDSA");
            verifier.initVerify(publicKey);
            verifier.update(signedPayload.getBytes(StandardCharsets.UTF_8));
            
            return verifier.verify(signatureBytes);
            
        } catch (Exception e) {
            System.err.println("Signature verification failed: " + e.getMessage());
            return false;
        }
    }
    
    public boolean isEventProcessed(String eventId) {
        return processedEvents.contains(eventId);
    }
    
    public void markEventProcessed(String eventId) {
        processedEvents.add(eventId);
        System.out.println("Marking event as processed: " + eventId);
    }
    
    public void handleWebhookEvent(Map<String, Object> event) throws Exception {
        String eventId = (String) event.get("id");
        
        // Make processing idempotent
        if (isEventProcessed(eventId)) {
            System.out.println("Event already processed: " + eventId);
            return;
        }
        
        String eventType = (String) event.get("type");
        @SuppressWarnings("unchecked")
        Map<String, Object> eventData = (Map<String, Object>) event.get("data");
        
        switch (eventType) {
            case "transaction.auto.updated":
                handleTransactionUpdate(eventData);
                break;
            case "customer.kyb_status.created":
            case "customer.kyb_status.updated":
                handleCustomerUpdate(eventData);
                break;
            default:
                System.out.println("Unknown event type: " + eventType);
        }
        
        // Mark as processed
        markEventProcessed(eventId);
    }
    
    private void handleTransactionUpdate(Map<String, Object> data) {
        @SuppressWarnings("unchecked")
        Map<String, Object> obj = (Map<String, Object>) data.get("object");
        String transactionId = (String) obj.get("id");
        String status = (String) obj.get("status");
        System.out.println("Processing transaction update: " + transactionId + " -> " + status);
        // Your transaction handling logic here
    }
    
    private void handleCustomerUpdate(Map<String, Object> data) {
        @SuppressWarnings("unchecked")
        Map<String, Object> obj = (Map<String, Object>) data.get("object");
        String customerId = (String) obj.get("customer_id");
        String kybStatus = (String) obj.get("kyb_status");
        System.out.println("Processing customer update: " + customerId + " -> " + kybStatus);
        // Your customer handling logic here
    }
}

@RestController
public class WebhookController {
    private final WebhookVerifier webhookVerifier;
    
    public WebhookController() throws Exception {
        String publicKeyHex = System.getenv("DAKOTA_WEBHOOK_PUBLIC_KEY");
        if (publicKeyHex == null || publicKeyHex.isEmpty()) {
            throw new IllegalStateException("DAKOTA_WEBHOOK_PUBLIC_KEY environment variable is required");
        }
        this.webhookVerifier = new WebhookVerifier(publicKeyHex);
    }
    
    @PostMapping("/webhooks/dakota")
    public ResponseEntity<String> handleWebhook(
            @RequestBody Map<String, Object> event,
            HttpServletRequest request) throws IOException {
        
        String signature = request.getHeader("X-Webhook-Signature");
        String timestamp = request.getHeader("X-Webhook-Timestamp");
        
        // Get raw body for signature verification
        String rawBody = new com.fasterxml.jackson.databind.ObjectMapper()
            .writeValueAsString(event);
        
        // Verify webhook signature
        boolean isValid = webhookVerifier.verifySignature(signature, timestamp, rawBody);
        
        if (!isValid) {
            System.err.println("Webhook signature verification failed");
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body("Unauthorized");
        }
        
        System.out.println("Received verified webhook: " + 
            event.get("type") + " " + event.get("id"));
        
        try {
            // Process the event
            webhookVerifier.handleWebhookEvent(event);
            
            // Respond with 200 to acknowledge receipt
            return ResponseEntity.ok("OK");
        } catch (Exception e) {
            System.err.println("Error processing webhook event: " + e.getMessage());
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body("Internal Server Error");
        }
    }
}

package main

import (
    "crypto/ed25519"
    "encoding/base64"
    "encoding/json"
    "fmt"
    "io"
    "log"
    "net/http"
    "os"
    "strconv"
    "sync"
    "time"
)

type WebhookEvent struct {
    ID         string           `json:"id"`
    Type       string           `json:"type"`
    Created    int64            `json:"created"`
    APIVersion string           `json:"api_version"`
    Data       WebhookEventData `json:"data"`
}

type WebhookEventData struct {
    Object             map[string]interface{} `json:"object"`
    PreviousAttributes map[string]interface{} `json:"previous_attributes,omitempty"` // reserved by the envelope; not populated by any event today
}

type WebhookHandler struct {
    publicKey       ed25519.PublicKey
    processedEvents map[string]bool
    mutex          sync.RWMutex
}

func NewWebhookHandler(publicKeyHex string) (*WebhookHandler, error) {
    publicKeyBytes, err := hex.DecodeString(publicKeyHex)
    if err != nil {
        return nil, fmt.Errorf("failed to decode public key: %v", err)
    }
    
    // Validate key length (Ed25519 public key should be 32 bytes)
    if len(publicKeyBytes) != 32 {
        return nil, fmt.Errorf("invalid Ed25519 public key length: %d", len(publicKeyBytes))
    }
    
    return &WebhookHandler{
        publicKey:       ed25519.PublicKey(publicKeyBytes),
        processedEvents: make(map[string]bool),
    }, nil
}

func (wh *WebhookHandler) verifySignature(signature, timestamp, body string) bool {
    if signature == "" || timestamp == "" || body == "" {
        log.Println("Missing required parameters for signature verification")
        return false
    }
    
    // Check timestamp to prevent replay attacks (within 5 minutes)
    webhookTime, err := strconv.ParseInt(timestamp, 10, 64)
    if err != nil {
        log.Printf("Invalid timestamp format: %v", err)
        return false
    }
    
    currentTime := time.Now().Unix()
    timeDifference := currentTime - webhookTime
    if timeDifference > 300 || timeDifference < -300 { // 5 minutes
        log.Println("Webhook timestamp too old or too far in future")
        return false
    }
    
    // Create the signed payload
    signedPayload := timestamp + body
    
    // Decode signature
    signatureBytes, err := base64.StdEncoding.DecodeString(signature)
    if err != nil {
        log.Printf("Failed to decode signature: %v", err)
        return false
    }
    
    // Verify signature
    return ed25519.Verify(wh.publicKey, []byte(signedPayload), signatureBytes)
}

func (wh *WebhookHandler) isEventProcessed(eventID string) bool {
    wh.mutex.RLock()
    defer wh.mutex.RUnlock()
    return wh.processedEvents[eventID]
}

func (wh *WebhookHandler) markEventProcessed(eventID string) {
    wh.mutex.Lock()
    defer wh.mutex.Unlock()
    wh.processedEvents[eventID] = true
    log.Printf("Marking event as processed: %s", eventID)
}

func (wh *WebhookHandler) handleWebhookEvent(event WebhookEvent) {
    // Make processing idempotent
    if wh.isEventProcessed(event.ID) {
        log.Printf("Event already processed: %s", event.ID)
        return
    }
    
    switch event.Type {
    case "transaction.auto.updated":
        wh.handleTransactionUpdate(event.Data.Object)
    case "customer.kyb_status.created", "customer.kyb_status.updated":
        wh.handleCustomerUpdate(event.Data.Object)
    default:
        log.Printf("Unknown event type: %s", event.Type)
    }
    
    // Mark as processed
    wh.markEventProcessed(event.ID)
}

func (wh *WebhookHandler) handleTransactionUpdate(obj map[string]interface{}) {
    transactionID, _ := obj["id"].(string)
    status, _ := obj["status"].(string)
    log.Printf("Processing transaction update: %s -> %s", transactionID, status)
    // Your transaction handling logic here
}

func (wh *WebhookHandler) handleCustomerUpdate(obj map[string]interface{}) {
    customerID, _ := obj["customer_id"].(string)
    kybStatus, _ := obj["kyb_status"].(string)
    log.Printf("Processing customer update: %s -> %s", customerID, kybStatus)
    // Your customer handling logic here
}

func (wh *WebhookHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
        return
    }
    
    // Read request body
    body, err := io.ReadAll(r.Body)
    if err != nil {
        log.Printf("Failed to read request body: %v", err)
        http.Error(w, "Bad request", http.StatusBadRequest)
        return
    }
    defer r.Body.Close()
    
    signature := r.Header.Get("X-Webhook-Signature")
    timestamp := r.Header.Get("X-Webhook-Timestamp")
    
    // Verify webhook signature
    if !wh.verifySignature(signature, timestamp, string(body)) {
        log.Println("Webhook signature verification failed")
        http.Error(w, "Unauthorized", http.StatusUnauthorized)
        return
    }
    
    // Parse webhook event
    var event WebhookEvent
    if err := json.Unmarshal(body, &event); err != nil {
        log.Printf("Failed to parse webhook event: %v", err)
        http.Error(w, "Bad request", http.StatusBadRequest)
        return
    }
    
    log.Printf("Received verified webhook: %s %s", event.Type, event.ID)
    
    // Process the event
    wh.handleWebhookEvent(event)
    
    // Respond with 200 to acknowledge receipt
    w.WriteHeader(http.StatusOK)
    w.Write([]byte("OK"))
}

func main() {
    publicKeyHex := os.Getenv("DAKOTA_WEBHOOK_PUBLIC_KEY")
    if publicKeyHex == "" {
        log.Fatal("DAKOTA_WEBHOOK_PUBLIC_KEY environment variable is required")
    }
    
    webhookHandler, err := NewWebhookHandler(publicKeyHex)
    if err != nil {
        log.Fatalf("Failed to create webhook handler: %v", err)
    }
    
    http.Handle("/webhooks/dakota", webhookHandler)
    
    port := os.Getenv("PORT")
    if port == "" {
        port = "3000"
    }
    
    log.Printf("Starting webhook server on port %s", port)
    log.Fatal(http.ListenAndServe(":"+port, nil))
}

Managing Webhooks

List Webhooks

List all webhook targets configured for your account:

cURL

curl -X GET https://api.platform.dakota.xyz/webhooks/targets \
  -H "X-API-Key: your-api-key"

const response = await fetch('https://api.platform.dakota.xyz/webhooks/targets', {
  headers: {
    'X-API-Key': 'your-api-key'
  }
});

const webhooks = await response.json();
console.log(`Found ${webhooks.data.length} webhook targets`);

import requests

response = requests.get(
    'https://api.platform.dakota.xyz/webhooks/targets',
    headers={'X-API-Key': 'your-api-key'}
)

webhooks = response.json()
print(f'Found {len(webhooks["data"])} webhook targets')

package main

import (
    "net/http"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.platform.dakota.xyz/webhooks/targets", nil)
    
    req.Header.Add("X-API-Key", "your-api-key")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

use reqwest::header::{HeaderMap, HeaderValue};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    
    let response = client
        .get("https://api.platform.dakota.xyz/webhooks/targets")
        .headers(headers)
        .send()
        .await?;
    
    Ok(())
}

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class DakotaListWebhooksExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/webhooks/targets"))
            .header("X-API-Key", "your-api-key")
            .GET()
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Update Webhook

Update an existing webhook target:

cURL

curl -X PATCH https://api.platform.dakota.xyz/webhooks/targets/{webhook_id} \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "global": false
  }'

const response = await fetch(`https://api.platform.dakota.xyz/webhooks/targets/${webhookId}`, {
  method: 'PATCH',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    global: false
  })
});

import requests
import uuid

response = requests.patch(
    f'https://api.platform.dakota.xyz/webhooks/targets/{webhook_id}',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4()),
        'Content-Type': 'application/json'
    },
    json={'global': False}
)

package main

import (
    "bytes"
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    body := bytes.NewBufferString(`{"global": false}`)
    
    req, _ := http.NewRequest("PATCH", "https://api.platform.dakota.xyz/webhooks/targets/" + webhookId, body)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    req.Header.Add("Content-Type", "application/json")
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    headers.insert("Content-Type", HeaderValue::from_static("application/json"));
    
    let body = json!({"global": false});
    
    let response = client
        .patch(&format!("https://api.platform.dakota.xyz/webhooks/targets/{}", webhook_id))
        .headers(headers)
        .json(&body)
        .send()
        .await?;
    
    Ok(())
}

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaUpdateWebhookExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = "{\"global\": false}";
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/webhooks/targets/" + webhookId))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .header("Content-Type", "application/json")
            .method("PATCH", HttpRequest.BodyPublishers.ofString(body))
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

Delete Webhook

Delete a webhook target:

cURL

curl -X DELETE https://api.platform.dakota.xyz/webhooks/targets/{webhook_id} \
  -H "X-API-Key: your-api-key" \
  -H "X-Idempotency-Key: $(uuidgen)"

const response = await fetch(`https://api.platform.dakota.xyz/webhooks/targets/${webhookId}`, {
  method: 'DELETE',
  headers: {
    'X-API-Key': 'your-api-key',
    'X-Idempotency-Key': crypto.randomUUID()
  }
});

if (response.ok) {
  console.log('Webhook deleted successfully');
}

import requests
import uuid

response = requests.delete(
    f'https://api.platform.dakota.xyz/webhooks/targets/{webhook_id}',
    headers={
        'X-API-Key': 'your-api-key',
        'X-Idempotency-Key': str(uuid.uuid4())
    }
)

if response.status_code == 204:
    print('Webhook deleted successfully')

package main

import (
    "net/http"
    "github.com/google/uuid"
)

func main() {
    client := &http.Client{}
    req, _ := http.NewRequest("DELETE", "https://api.platform.dakota.xyz/webhooks/targets/" + webhookId, nil)
    
    req.Header.Add("X-API-Key", "your-api-key")
    req.Header.Add("X-Idempotency-Key", uuid.New().String())
    
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

use reqwest::header::{HeaderMap, HeaderValue};
use uuid::Uuid;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    
    let mut headers = HeaderMap::new();
    headers.insert("X-API-Key", HeaderValue::from_static("your-api-key"));
    headers.insert("X-Idempotency-Key", HeaderValue::from_str(&Uuid::new_v4().to_string())?);
    
    let response = client
        .delete(&format!("https://api.platform.dakota.xyz/webhooks/targets/{}", webhook_id))
        .headers(headers)
        .send()
        .await?;
    
    Ok(())
}

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.UUID;

public class DakotaDeleteWebhookExample {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.platform.dakota.xyz/webhooks/targets/" + webhookId))
            .header("X-API-Key", "your-api-key")
            .header("X-Idempotency-Key", UUID.randomUUID().toString())
            .DELETE()
            .build();
            
        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

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

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 timestamps — created 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:

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

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:

// Robust webhook event processing with error handling
class WebhookProcessor {
  constructor() {
    this.processedEvents = new Set(); // Use Redis/database in production
    this.maxRetries = 3;
  }

  async handleWebhookEvent(event) {
    const eventId = event.id;
    
    // Make processing idempotent
    if (this.isEventAlreadyProcessed(eventId)) {
      console.log('Event already processed:', eventId);
      return { success: true, message: 'Already processed' };
    }

    try {
      await this.processEventWithRetry(event);
      this.markEventAsProcessed(eventId);
      return { success: true, message: 'Event processed successfully' };
    } catch (error) {
      console.error('Failed to process event after retries:', error);
      await this.storeFailedEvent(event, error);
      throw error;
    }
  }

  async processEventWithRetry(event, attempt = 1) {
    try {
      await this.processEvent(event);
    } catch (error) {
      if (attempt < this.maxRetries) {
        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
        console.log(`Retrying event processing in ${delay}ms (attempt ${attempt + 1})`);
        await new Promise(resolve => setTimeout(resolve, delay));
        return this.processEventWithRetry(event, attempt + 1);
      }
      throw error;
    }
  }

  async processEvent(event) {
    console.log(`Processing event: ${event.type} (${event.id})`);
    
    switch (event.type) {
      case 'transaction.auto.created':
        await this.handleTransactionCreated(event.data);
        break;
      case 'transaction.auto.updated':
        // Inspect event.data.object.status to distinguish processing/completed/failed
        await this.handleTransactionUpdate(event.data);
        break;
      case 'customer.kyb_status.created':
      case 'customer.kyb_status.updated':
        await this.handleCustomerKybUpdate(event.data);
        break;
      case 'customer.created':
        await this.handleCustomerCreated(event.data);
        break;
      default:
        console.log(`Unknown event type: ${event.type}`);
    }
  }

  async handleTransactionUpdate(data) {
    const obj = data.object || {};
    console.log(`Transaction ${obj.id} status: ${obj.status}`);
    await this.updateTransactionStatus(obj.id, obj.status);
    
    if (obj.status === 'completed') {
      await this.notifyTransactionCompleted(obj);
    } else if (obj.status === 'failed') {
      await this.notifyTransactionFailed(obj);
    }
  }

  async handleTransactionCompleted(data) {
    const obj = data.object || {};
    console.log(`Transaction completed: ${obj.id}`);
    await this.updateTransactionStatus(obj.id, 'completed');
    await this.notifyTransactionCompleted(obj);
    await this.triggerPostCompletionActions(obj);
  }

  async handleTransactionFailed(data) {
    const obj = data.object || {};
    console.log(`Transaction failed: ${obj.id}`, obj.failure_reason);
    await this.updateTransactionStatus(obj.id, 'failed');
    await this.notifyTransactionFailed(obj);
    await this.handleTransactionFailure(obj);
  }

  async handleCustomerKybUpdate(data) {
    const obj = data.object || {};
    console.log(`Customer ${obj.customer_id} KYB status: ${obj.kyb_status}`);
    await this.updateCustomerKybStatus(obj.customer_id, obj.kyb_status);
    
    if (obj.kyb_status === 'approved') {
      await this.notifyCustomerApproved(obj);
      await this.enableCustomerFeatures(obj.customer_id);
    } else if (obj.kyb_status === 'rejected') {
      await this.notifyCustomerRejected(obj);
      await this.handleKybRejection(obj);
    }
  }

  async handleCustomerCreated(data) {
    const obj = data.object || {};
    console.log(`New customer created: ${obj.customer_id}`);
    await this.syncCustomerToDatabase(obj);
    await this.sendWelcomeEmail(obj);
  }

  isEventAlreadyProcessed(eventId) {
    return this.processedEvents.has(eventId);
  }

  markEventAsProcessed(eventId) {
    this.processedEvents.add(eventId);
    console.log('Marked event as processed:', eventId);
  }

  async storeFailedEvent(event, error) {
    console.log('Storing failed event for review:', event.id, error.message);
    // Store in database for manual review
  }

  // Business logic methods (implement according to your needs)
  async updateTransactionStatus(transactionId, status) { /* Your implementation */ }
  async notifyTransactionCompleted(data) { /* Your implementation */ }
  async notifyTransactionFailed(data) { /* Your implementation */ }
  async triggerPostCompletionActions(data) { /* Your implementation */ }
  async handleTransactionFailure(data) { /* Your implementation */ }
  async updateCustomerKybStatus(customerId, status) { /* Your implementation */ }
  async notifyCustomerApproved(data) { /* Your implementation */ }
  async notifyCustomerRejected(data) { /* Your implementation */ }
  async enableCustomerFeatures(customerId) { /* Your implementation */ }
  async handleKybRejection(data) { /* Your implementation */ }
  async syncCustomerToDatabase(data) { /* Your implementation */ }
  async sendWelcomeEmail(data) { /* Your implementation */ }
}

// Usage in Express route
const webhookProcessor = new WebhookProcessor();

app.post('/webhooks/dakota', async (req, res) => {
  // ... signature verification code ...
  
  try {
    const result = await webhookProcessor.handleWebhookEvent(event);
    console.log(result.message);
    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook processing failed:', error);
    res.status(200).send('Processing failed but acknowledged');
  }
});

# Python implementation here - abbreviated for clarity

# Go implementation here - abbreviated for clarity

# Rust implementation here - abbreviated for clarity

# Java implementation here - abbreviated for clarity

Testing Webhooks

Local Development

Use tools like ngrok to expose local endpoints:

ngrok http 3000
# Use the HTTPS URL for webhook registration

Webhook Testing

Test your webhook endpoint manually:

curl -X POST https://your-app.com/webhooks/dakota \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: base64_encoded_signature" \
  -H "X-Webhook-Timestamp: $(date +%s)" \
  -d '{
    "type": "transaction.auto.updated",
    "data": {
      "object": {
        "id": "31TgvtxUdXi95dUN4M8X1rhSCNS",
        "status": "completed"
      }
    }
  }'

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

Below are the commonly used webhook event types. This list is not exhaustive — the authoritative list of subscribable event types is the EventType enum in the API reference.

Event	Description
Customer Events
`customer.created`	New customer created
`customer.updated`	Customer information updated (not currently emitted)
`customer.deleted`	Customer deleted (delivered to targets subscribed to all events; not yet selectable in an `event_types` filter)
`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
`customer.capability_status.updated`	Customer’s standing for a capability (rail) changed
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

​Overview

​Webhook Signature Verification

​Dakota Public Keys

​Signature Headers

​Setting Up Webhooks

​1. Create a Webhook Endpoint

​2. Register Your Webhook

​Webhook Target Fields

​Webhook Events

​Transaction Events

​Status progression

​Fee fields in the receipt

​Customer Events

​Request for Information (RFI) Events

​Reading requirements

​Where to get the resubmission link

​Resolving a request

​Handling the events

​Application status changes that do not emit a webhook

​Verification Code Examples

​Managing Webhooks

​List Webhooks

​Update Webhook

​Delete Webhook

​Webhook Delivery

​Retry Policy

​Success Criteria

​Failure Handling

​Event Ordering

​Webhook Headers

​Best Practices

​Endpoint Requirements

​Security

​Processing Best Practices

​Testing Webhooks

​Local Development

​Webhook Testing

​Troubleshooting

​Common Issues

​Monitoring

​Event Types Reference

​Next Steps

​API Reference

Overview

Webhook Signature Verification

Dakota Public Keys

Signature Headers

Setting Up Webhooks

1. Create a Webhook Endpoint

2. Register Your Webhook

Webhook Target Fields

Webhook Events

Transaction Events

Status progression

Fee fields in the receipt

Customer Events

Request for Information (RFI) Events

Reading `requirements`

Where to get the resubmission link

Resolving a request

Handling the events

Application status changes that do not emit a webhook

Verification Code Examples

Managing Webhooks

List Webhooks

Update Webhook

Delete Webhook

Webhook Delivery

Retry Policy

Success Criteria

Failure Handling

Event Ordering

Webhook Headers

Best Practices

Endpoint Requirements

Security

Processing Best Practices

Testing Webhooks

Local Development

Webhook Testing

Troubleshooting

Common Issues

Monitoring

Event Types Reference

Next Steps

API Reference