
Key Features
Webhooks provide real-time delivery with built-in security, automatic retries, and event filtering. All official SDKs include signature verification helpers, and the dashboard offers testing, monitoring, and replay tools.Getting Started
Go to Developer → Webhooks
Click Add Endpoint
Enter Your Endpoint URL
Select Events
Save
Integration Connectors
Route webhook events directly to third-party services using integration connectors, eliminating the need to build and maintain custom webhook handlers.How Connectors Work
A connector transforms Dodo Payments events into the format the destination expects. Which details you provide depends on the destination:Setting Up a Connector
When creating or editing an endpoint, select a connector and the side sheet shows setup instructions for that destination. Test the transformation before saving to confirm events are converted correctly.Configuring Subscribed Events
Configure which events each webhook endpoint receives.Navigate to Webhook Endpoints
Open Event Configuration
Select Events
payment, subscription, dispute). Check the boxes next to the events you want to receive. You can select individual events, an entire resource, or mix and match.Save Configuration
Event Catalog
Go to Developer → Webhooks and open the Event catalog tab to see every event type Dodo Payments can send. Select an event to view its schema and sample payload.Webhook Events Guide
Webhook Delivery
Timeouts
Webhooks में connection और read operations, दोनों के लिए 30-second timeout होता है। Webhooks को asynchronous रूप से process करें और तुरंत200 status code लौटाएँ, फिर event को background में handle करें।
Automatic Retries
विफल deliveries को exponential backoff के साथ कुल 8 attempts तक दोबारा try किया जाता है:Idempotency
प्रत्येक webhook में एक uniquewebhook-id header शामिल होता है। Duplicate events का पता लगाने और उन्हें skip करने के लिए इस ID को store करें, क्योंकि retries के कारण एक ही event कई बार deliver हो सकता है।
Event Ordering
Retries या network conditions के कारण events क्रम से बाहर आ सकते हैं। प्रत्येक webhook में एकtimestamp field शामिल होता है; यदि आपके application को इसकी आवश्यकता हो, तो events का क्रम निर्धारित करने के लिए इसका उपयोग करें। आपको delivery के समय की latest payload state हमेशा प्राप्त होती है।
Securing Webhooks
Webhook payloads को हमेशा validate करें और HTTPS का उपयोग करें।Verifying Signatures
प्रत्येक webhook में एकwebhook-signature header शामिल होता है: यह payload और timestamp का HMAC SHA256 signature है, जिसे आपकी secret key से sign किया जाता है।
SDK Verification (Recommended)
सभी official SDKs में built-in helpers शामिल हैं। Client को initialize करते समयDODO_PAYMENTS_WEBHOOK_KEY सेट करें, फिर payload को verify और parse करने के लिए unwrap() call करें। दो methods उपलब्ध हैं:
unwrap— आपकी webhook secret key से signature verify करता है, फिर payload को parse करता है।unsafe_unwrap— बिना verification के payload को parse करता है। इसका उपयोग केवल testing के लिए करें।
unwrap / unsafeUnwrap, Python में unwrap / unsafe_unwrap, और Go में Unwrap / UnsafeUnwrap।
Manual Verification (Alternative)
यदि आप SDK का उपयोग नहीं कर रहे हैं, तो signature को स्वयं verify करें:webhook-id,webhook-timestampऔर raw request body को periods से जोड़कर signed content बनाएँ:{id}.{timestamp}.{body}। Raw body को ठीक उसी रूप में उपयोग करें जिस रूप में प्राप्त हुआ है, किसी भी JSON parsing से पहले।- अपनी webhook secret लें। यदि यह
whsec_से शुरू होती है, तो उस prefix को हटाएँ, फिर signing key प्राप्त करने के लिए बाकी हिस्से को base64-decode करें। - Signing key के साथ signed content का HMAC-SHA256 compute करें और परिणाम को base64-encode करें।
webhook-signatureheader में एक या अधिक space-separated signatures होते हैं, जिनमें प्रत्येकv1,<base64-signature>के रूप में होता है। यदि कोईv1signature आपके signature से match करता है, तो request valid है। तुलना के लिए constant-time function का उपयोग करें।- Replay attacks को रोकने के लिए यदि
webhook-timestampcurrent time से बहुत अलग हो, तो request reject करें। Standard Webhooks libraries 5 minutes की अनुमति देती हैं।
Source IP Addresses
Signature verification समर्थित authentication method है। यह साबित करता है कि request आपकी webhook secret से sign की गई थी, जो network-level check नहीं कर सकता। Webhook deliveries IP addresses के ऐसे pool से आती हैं जो समय के साथ बदलता रहता है। Authentication के लिए IP allowlists पर निर्भर न रहें। इसके बजाय हमेशाwebhook-signature header को verify करें, जैसा कि Verifying Signatures में बताया गया है।
यदि आपके firewall को allowlist की आवश्यकता है:
- Addresses को स्थायी रूप से hardcode न करें। Ranges समय के साथ बदलते हैं और पुराने rules deliveries को चुपचाप block कर देते हैं।
- Firewall को lock down करने से पहले support@dodopayments.com से current ranges का अनुरोध करें।
- Change notices पर नज़र रखें। जब delivery addresses बदलते हैं, तो हम प्रभावित merchants को email से सूचित करते हैं — बताई गई date से पहले updates लागू करें।
- आपके द्वारा जोड़े गए network rules के बावजूद signature verification enabled रखें।
Responding to Webhooks
Receipt acknowledge करने के लिए आपके webhook handler को2xx status code लौटाना होगा। किसी भी अन्य response को failure माना जाता है और webhook को retry किया जाएगा।
Best Practices
- केवल HTTPS का उपयोग करें। HTTP endpoints interception के प्रति vulnerable होते हैं।
- तुरंत response दें। तुरंत
200status code लौटाएँ, फिर event को asynchronously process करें। - Idempotency लागू करें। Duplicate events का पता लगाने और उन्हें skip करने के लिए
webhook-idheader का उपयोग करें। - अपनी secret को सुरक्षित रखें।
DODO_PAYMENTS_WEBHOOK_KEYको environment variables या secrets manager में store करें, कभी भी version control में नहीं।
Webhook Payload Structure
Request Format
Headers
Request Body
payment.succeeded, subscription.active)।Example Payload
Event Types
Event Payloads
Handle Payment Failures
payment.failed पर react करें और declined payments recover करेंTesting Webhooks
Send an Example Event
अपने webhook integration को सीधे dashboard से test करें:Navigate to Webhooks
Open Testing Tab
Send Example
Check Your Endpoint
2xx status code लौटाया है।Implementation Example
Webhook verification और handling के साथ complete Express.js implementation:Testing Webhooks with the CLI
Dodo Payments CLI में local development के दौरान webhooks test करने के लिए दो commands हैं।Listen for Live Webhooks Locally
अपने test mode account से वास्तविक webhook events को local development server पर forward करें:http://localhost:3000/webhook) पर forward करता है तथा signature verification testing के लिए सभी headers को सुरक्षित रखता है।
dodo login चलाएँ और पहले Test Mode चुनें।Trigger Mock Webhook Events
Real transactions बनाए बिना किसी भी endpoint पर mock webhook payloads भेजें:subscription.past_due या subscription.unpaused नहीं भेजता। Exact list के लिए Supported Webhook Events देखें।
CLI Webhook Testing Docs
Advanced Settings
Advanced tab आपके webhook endpoint behavior को fine-tune करने के लिए अतिरिक्त configuration options प्रदान करता है।Rate Limiting (Throttling)
आपके endpoint पर webhook events deliver होने की rate नियंत्रित करें। Default रूप से webhooks पर कोई rate limit लागू नहीं होती और events होने के तुरंत बाद deliver किए जाते हैं।Open Advanced Tab
Configure Rate Limit
Set Your Limit
Custom Headers
अपने endpoint पर भेजे जाने वाले सभी webhook requests में custom HTTP headers जोड़ें। यह authentication, routing या metadata जोड़ने के लिए उपयोगी है।Add Headers
Add Multiple Headers
Transformations
Transformations आपको webhook payload को modify करने और वैकल्पिक रूप से उसे किसी अलग URL पर redirect करने देती हैं। Transformations का उपयोग करें:- Processing से पहले payload structure modify करने के लिए
- Content के आधार पर webhooks को अलग-अलग endpoints पर route करने के लिए
- Payload में fields जोड़ने या हटाने के लिए
- Data formats transform करने के लिए
Enable Transformations
Configure Transformation
handler() से webhook object return करना होगा।Test Transformation
Monitoring Webhook Logs
Logs tab आपके webhook delivery status की visibility प्रदान करता है।Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- Complete webhook payload
- Response code और duration के साथ प्रत्येक delivery attempt
- प्रत्येक attempt का timestamp
- आपके endpoint से प्राप्त कोई भी error messages
Activity Monitoring
अपने endpoints पर delivery performance देखने के लिए Developer → Webhooks पर जाएँ और Activity tab खोलें। Delivery activity समय के साथ attempts को plot करता है, जिन्हें window के आधार पर Attempts per 5 minutes, Attempts per hour या Attempts per day में bucket किया जाता है। प्रत्येक bar outcome के अनुसार विभाजित होती है और किसी segment पर hover करने से status, attempts की संख्या और total में उसका share दिखाई देता है। किसी endpoint पर Overview tab में Delivery stats (last 24h) पिछले दिन की यही जानकारी summarize करता है।Replaying and Recovering Messages
किसी message को दोबारा भेजने का तरीका इस बात पर निर्भर करता है कि आपको कितने messages की आवश्यकता है:- One message — इसे Logs tab से खोलें और attempt पर Replay action का उपयोग करें।
- A range of messages — endpoint खोलें, क्योंकि bulk modes एक समय में केवल एक endpoint पर काम करते हैं।
Replaying in Bulk
Developer → Webhooks से endpoint खोलें। तीन modes उपलब्ध हैं और प्रत्येक केवल उसी endpoint पर काम करता है:Open More Actions
Set the Range
Start the Run