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.succeededThe 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.expiredThe session expired before it was paid, or you expired it through the API. Release held stock.
refund.succeededA 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.testSent 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.
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.
- Attempt 1Immediately
- Attempt 21 minute
- Attempt 35 minutes
- Attempt 430 minutes
- Attempt 52 hours
- Attempt 66 hours
- Attempt 712 hours
- 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.