Webhooks

We send a signed POST to your webhook URL when a payment succeeds, a session expires or a refund completes. Verify the signature, answer with a 2xx status, and we stop retrying.

Last updated:

Events

  • payment.succeeded

    The payment was confirmed on-chain and the session is now paid. This is the event to fulfil an order on.

    • tx_signature: Solana transaction signature. Open it on Solscan to audit the payment.
    • payer: Wallet address that paid.
    • pay_token: Token the customer paid with, always DTAI.
    • settled_token: Token your payout wallet received.
    • final_usd: The order price in USD. The customer pays this amount converted to DTAI at the live price.
    • discount_usd: Always 0. There are no discounts.
  • payment.expired

    The session expired before it was paid, or you expired it through the API. Release held stock.

  • refund.succeeded

    A refund was confirmed on-chain and the session is now refunded.

    • refund_id: Identifier of the refund.
    • refund_amount: Amount sent back, in the refund token.
    • refund_token: Token that was refunded.
    • refund_tx_signature: Transaction signature of the refund.
    • customer_wallet: Wallet that received the refund.
  • webhook.test

    Sent only when you call POST /api/v1/webhooks/test. It has no session and is never retried.

    • message: A fixed test message.

Session events also carry these fields in data: session_id, order_id, status, amount, currency, amount_usd, discount_percent, settlement_token, customer_email, metadata, livemode.

POST /your/webhook
Content-Type: application/json
X-DTAI-Event: payment.succeeded
X-DTAI-Signature: t=1760000000,v1=5257a869e7ec...

{
  "id": "evt_Xk29aPq0LmB7vZc3Nd81WqRt",
  "type": "payment.succeeded",
  "created": 1760000000,
  "data": {
    "session_id": "cs_test_k3Jd8sLq0WmA2xP9tR7vYb1Z",
    "order_id": "1001",
    "status": "paid",
    "amount": 49.99,
    "currency": "USD",
    "amount_usd": 49.99,
    "discount_percent": 0,
    "settlement_token": "DTAI",
    "customer_email": "jane@example.com",
    "metadata": { "cart_id": "abc" },
    "livemode": false,
    "tx_signature": "5Qm3...Hx9",
    "payer": "2vYA...iMzs",
    "pay_token": "DTAI",
    "settled_token": "DTAI",
    "final_usd": 49.99,
    "discount_usd": 0
  }
}

Verify the signature

The signature is the HMAC-SHA256 of timestamp + "." + raw body, written as hex and sent as X-DTAI-Signature: t=timestamp,v1=signature. Reject events whose timestamp is more than five minutes old to block replays.

import { DTAI } from "@/lib/dtai-server.mjs"

const event = await DTAI.constructEvent(rawBody, signatureHeader, process.env.DTAI_WEBHOOK_SECRET)
// Throws a DTAIError if the signature is wrong or the timestamp is older than 5 minutes.

Signature tester

Paste a delivery from your logs to see whether your secret and body produce the signature we sent.

Everything runs in your browser. Nothing you paste is sent to our servers. Use a test mode secret.

Retries and recovery

A delivery that does not get a 2xx response is retried up to eight times in total, about 44 hours after the first attempt. After that it is marked failed, and you can still redeliver it.

  1. Attempt 1Immediately
  2. Attempt 21 minute
  3. Attempt 35 minutes
  4. Attempt 430 minutes
  5. Attempt 52 hours
  6. Attempt 66 hours
  7. Attempt 712 hours
  8. Attempt 824 hours
// Find events your server missed and send them again.
const { data } = await dtai.webhooks.deliveries({ status: "failed" })
for (const delivery of data) {
  await dtai.webhooks.redeliver(delivery.id)
}

Best practices

  • Verify the signature against the raw body. Parsing and re-serialising JSON changes the bytes and breaks the check.
  • Return a 2xx within a few seconds, then do slow work in a queue. Slow or failing responses are retried.
  • Treat events as at-least-once. The same event can arrive twice, so make fulfilment idempotent on order_id or the event id.
  • Do not rely on event order. A payment.expired event can reach you after a payment.succeeded event for a different session.
  • Check livemode before acting, so test events never fulfil real orders.
  • Reconcile with GET /api/v1/checkout/sessions if your endpoint was down for a long time.