Webhooks

​

Webhook Overview

​

Dodo Webhook

​

Endpoint

POST /api/dodo/webhook
Content-Type: application/json

• Body parsing: Disabled (api.bodyParser: false) so the raw body can be used for signature verification.

​

Event Types

​

Security

​

Signature verification

• Header: x-dodo-signature or dodo-signature (single string; if array, treated as invalid).
• Secret: DODO_WEBHOOK_SECRET. If unset, verification is skipped (insecure in production).
• Algorithm: HMAC-SHA256 of the raw body (UTF-8), hex-encoded; compared with crypto.timingSafeEqual to the header value.
• On invalid signature: 401 { received: false, error: "Invalid signature" }.

​

Raw body

• The handler reads the raw body from req (stream) because Next.js does not parse it when bodyParser: false. The same bytes must be used for HMAC and for JSON.parse.

​

Retry Logic

• Server behavior: The handler always returns 200 (or 401 on bad signature) so Dodo does not retry on “success.”
• On processing errors (e.g. DB update fails): the handler still returns 200 and { received: true, error: message } to avoid retries for malformed or unprocessable payloads. Log errors for debugging.
• Dodo: Configure retries and backoff in the Dodo dashboard. No custom retry logic is implemented in Scriptonia.

​

Examples

​

payment.succeeded (conceptual)

{
  "type": "payment.succeeded",
  "data": {
    "payment_id": "pay_xxx",
    "id": "pay_xxx",
    "metadata": {
      "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "platform": "Web Application"
    }
  }
}

​

Refund

{
  "type": "refund.succeeded",
  "data": {
    "metadata": { "session_id": "a1b2c3d4-..." }
  }
}