webhook-integration

Dodo Payments Webhook Integration

Webhooks deliver real-time notifications when payment events occur. Use them to automate workflows, update databases, send confirmations, and keep your systems in sync.

When to use this skill

• Setting up a webhook endpoint to receive payment, subscription, or refund events
• Implementing signature verification to ensure webhook authenticity
• Handling specific event types (payment succeeded, subscription renewed, etc.)
• Testing webhooks locally during development
• Ensuring idempotent webhook processing to handle retries

---

Core Concepts

Webhook: An HTTP POST request sent by Dodo to your endpoint when an event occurs.

Signature verification: Cryptographic proof that a webhook came from Dodo, not an attacker. Required for production.

Idempotency: Processing the same webhook multiple times produces the same result. Use the webhook-id header to detect and skip duplicates.

Raw body: The exact bytes received from Dodo, before parsing. Required for signature verification.

---

Setup: Creating a Webhook Endpoint

1. Create the endpoint in the dashboard

1. Go to Developer → Webhooks
2. Click Create Webhook
3. Enter your endpoint URL (must be HTTPS in production)
4. Select the events you want to receive
5. Copy the signing secret

2. Store the signing secret

export DODO_PAYMENTS_WEBHOOK_KEY=whsec_...

The SDK reads this automatically. You can also pass it explicitly when initializing the client.

---

Webhook Headers and Payload

Every webhook request includes three required headers (all lowercase, hyphenated):

Header	Example	Purpose
webhook-id	evt_abc123	Unique identifier for this webhook delivery
webhook-signature	v1,base64_signature_here	HMAC-SHA256 signature for verification
webhook-timestamp	1704067200	Unix timestamp (seconds) when the event was sent

The request body is JSON:

{
  "business_id": "bus_xxxxx",
  "type": "payment.succeeded",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "payload_type": "Payment",
    "payment_id": "pay_xxxxx",
    "status": "succeeded",
    "total_amount": 2999,
    "currency": "USD",
    "customer": {
      "customer_id": "cus_xxxxx",
      "email": "[email protected]",
      "name": "John Doe"
    }
  }
}