webhook-integration_skill

Overview

This skill is a complete guide for setting up and handling Dodo Payments webhooks to receive real-time payment and subscription event notifications. It explains secure signature verification, event handling patterns, and quick setup steps for common frameworks. The content focuses on production-ready practices: idempotency, replay protection, logging, and async processing.

How this skill works

The skill inspects incoming HTTP POST requests from Dodo Payments, verifies the webhook signature using the shared secret, checks the webhook-timestamp to prevent replay attacks, and parses the JSON event payload. It routes events by type (payment, subscription, refund, dispute, license_key) to handler functions, and recommends responding immediately while processing business logic asynchronously. Example implementations are provided for Next.js, Express, FastAPI, and Go.

When to use it

• You need real-time updates about payments, refunds, disputes, or license key creation.
• Automating order fulfillment, granting access, or updating subscription status.
• Integrating payment state into CRMs, analytics, or notification systems.
• Testing payment flows locally or exposing a dev endpoint with ngrok.
• Protecting endpoints from spoofed requests and replay attacks.

Best practices

• Always verify webhook signatures using the Dodo Payments secret and a timing-safe comparison.
• Check webhook-timestamp and reject requests older than a short tolerance (e.g., 5 minutes).
• Implement idempotency using webhook-id to avoid duplicate processing.
• Respond quickly (200 OK) and process heavy work asynchronously via a queue.
• Log events and errors with enough context to troubleshoot (event type, webhook-id, timestamp).

Example use cases

• Grant product access and send confirmation emails when payment.succeeded arrives.
• Retry or notify customers on payment.failed and update UI state.
• Activate or revoke subscription access on subscription.active and subscription.cancelled events.
• Update order status and revoke entitlements after refund.succeeded.
• Alert support and gather evidence when dispute.opened occurs.