Webhooks & Events

Kortana uses webhooks to notify your application when an event happens in your account. Webhooks are particularly useful for asynchronous events like when an on-chain transfer is confirmed or when a card is funded.

Testing Webhooks Locally

When developing locally, your server cannot receive webhooks directly from Kortana because it is behind a NAT or firewall. We recommend using a tool like ngrok or localtunnel to expose your local server to the internet.

1. Start Ngrok

ngrok http 3000

2. Register the URL

Copy the forwarding URL provided by ngrok (e.g., https://1234-abcd.ngrok.io) and append your webhook route (e.g., /api/webhooks). Save this in your Kortana Developer Dashboard.

3. Verify Signatures

All webhook requests contain a Kortana-Signature header. Use your Webhook Secret from the dashboard to verify the HMAC SHA-256 signature to ensure the request is authentically from Kortana.

Event Types & Payloads

Below are the standard event types emitted by the Kortana Ledger. Click on an event to see its payload structure.

Fired when an on-chain transfer of DNR is confirmed on the Kortana blockchain.

{
  "id": "evt_9a8b7c6d5e",
  "type": "wallet.transfer.completed",
  "created_at": "2026-07-04T12:00:00Z",
  "data": {
    "transferId": "111bb6c9-b55f-4f6e-bc1c-2dd043f2ac72",
    "amount": "1000",
    "currency": "DNR",
    "txHash": "0xb9f7ef80f26beadd7040bd1fa58e88f2dd1e8227...",
    "from": "0x3b6dbe334fe6faf71360dbbc74671a0c1c167608",
    "to": "0xf251038d1dB96Ce1a733Ae92247E0A6F400F275E",
    "status": "confirmed"
  }
}