
Key Features
Webhooks erbjuder leverans i realtid med inbyggd säkerhet, automatiska omförsök och händelsefiltrering. Alla officiella SDK:er innehåller hjälpfunktioner för signaturverifiering, och instrumentpanelen erbjuder verktyg för testning, övervakning och återuppspelning.Getting Started
Go to Developer → Webhooks
Click Add Endpoint
Enter Your Endpoint URL
Select Events
Save
Integrationsanslutningar
Vidarebefordra webhook-händelser direkt till tredjepartstjänster med hjälp av integrationsanslutningar, så att du slipper bygga och underhålla anpassade webhook-hanterare.Så fungerar anslutningar
En anslutning omvandlar Dodo Payments-händelser till det format som destinationen förväntar sig. Vilka uppgifter du behöver ange beror på destinationen:Konfigurera en anslutning
När du skapar eller redigerar en endpoint väljer du en anslutning, varpå sidopanelen visar konfigurationsinstruktioner för destinationen. Testa omvandlingen innan du sparar för att bekräfta att händelserna konverteras korrekt.Konfigurera prenumererade händelser
Konfigurera vilka händelser varje webhook-endpoint tar emot.Navigate to Webhook Endpoints
Open Event Configuration
Select Events
payment, subscription, dispute). Markera rutorna bredvid de händelser du vill ta emot. Du kan välja enskilda händelser, en hel resurs eller kombinera olika val.Save Configuration
Händelsekatalog
Gå till Developer → Webhooks och öppna fliken Event catalog för att se alla händelsetyper som Dodo Payments kan skicka. Välj en händelse för att visa dess schema och exempelpayload.Webhook Events Guide
Webhook-leverans
Tidsgränser
Webhooks har en timeout på 30 sekunder för både anslutnings- och läsoperationer. Bearbeta webhooks asynkront genom att omedelbart returnera en200-statuskod och sedan hantera händelsen i bakgrunden.
Automatiska omförsök
Misslyckade leveranser försöks om med exponentiell backoff, upp till totalt 8 försök:Idempotens
Varje webhook innehåller en unikwebhook-id-header. Spara detta ID för att upptäcka och hoppa över duplicerade händelser, eftersom omförsök kan leverera samma händelse flera gånger.
Händelseordning
Händelser kan komma i fel ordning på grund av omförsök eller nätverksförhållanden. Varje webhook innehåller etttimestamp-fält; använd det för att ordna händelser om din applikation kräver det. Du får alltid den senaste payload-statusen vid leveranstillfället.
Skydda webhooks
Validera alltid webhook-payloads och använd HTTPS.Verifiera signaturer
Varje webhook innehåller enwebhook-signature-header: en HMAC SHA256-signatur av payloaden och tidsstämpeln, signerad med din hemliga nyckel.
SDK-verifiering (rekommenderas)
Alla officiella SDK:er innehåller inbyggda hjälpfunktioner. AngeDODO_PAYMENTS_WEBHOOK_KEY när klienten initieras och anropa sedan unwrap() för att verifiera och parsa payloaden. Två metoder är tillgängliga:
unwrap— Verifierar signaturen med din webhook-hemliga nyckel och parsar sedan payloaden.unsafe_unwrap— Parsar payloaden utan att verifiera den. Använd den endast för testning.
unwrap / unsafeUnwrap i TypeScript, unwrap / unsafe_unwrap i Python och Unwrap / UnsafeUnwrap i Go.
Manuell verifiering (alternativ)
Om du inte använder ett SDK verifierar du signaturen själv:- Skapa det signerade innehållet genom att sammanfoga
webhook-id,webhook-timestampoch den råa request body:n med punkter:{id}.{timestamp}.{body}. Använd body:n exakt som den togs emot, innan någon JSON-parsning. - Ta din webhook-hemlighet. Om den börjar med
whsec_tar du bort det prefixet och base64-avkodar sedan resten för att få signeringsnyckeln. - Beräkna HMAC-SHA256 för det signerade innehållet med signeringsnyckeln och base64-koda resultatet.
webhook-signature-headern innehåller en eller flera blankstegsseparerade signaturer, var och en i formatetv1,<base64-signature>. Requesten är giltig om någonv1-signatur matchar din. Jämför med en constant-time-funktion.- Avvisa requesten om
webhook-timestampavviker för mycket från aktuell tid, för att förhindra replay-attacker. Standard Webhooks-biblioteken tillåter 5 minuter.
Käll-IP-adresser
Signaturverifiering är den autentiseringsmetod som stöds. Den bevisar att requesten signerades med din webhook-hemlighet, vilket en kontroll på nätverksnivå inte kan göra. Webhook-leveranser kommer från en pool av IP-adresser som ändras över tid. Förlita dig inte på IP-allowlistor för autentisering. Verifiera alltidwebhook-signature-headern i stället, enligt beskrivningen i Verifiera signaturer.
Om din brandvägg kräver en allowlista:
- Hårdkoda inte adresser permanent. Intervall ändras över tid och inaktuella regler blockerar leveranser utan tydlig indikation.
- Begär aktuella intervall från support@dodopayments.com innan du låser ner en brandvägg.
- Var uppmärksam på ändringsmeddelanden. När leveransadresser ändras meddelar vi berörda merchants via e-post — tillämpa uppdateringarna före det angivna datumet.
- Behåll signaturverifiering aktiverad oavsett vilka nätverksregler du lägger till.
Svara på webhooks
Din webhook-handler måste returnera en2xx status code för att bekräfta mottagandet. Alla andra svar behandlas som ett fel och webhooken försöks om.
Bästa praxis
- Använd endast HTTPS. HTTP-endpoints är sårbara för avlyssning.
- Svara omedelbart. Returnera en
200-statuskod direkt och bearbeta sedan händelsen asynkront. - Implementera idempotens. Använd
webhook-id-headern för att upptäcka och hoppa över duplicerade händelser. - Skydda din hemlighet. Lagra
DODO_PAYMENTS_WEBHOOK_KEYi miljövariabler eller en secrets manager, aldrig i versionshantering.
Webhook-payloadens struktur
Request-format
Headers
Request body
payment.succeeded, subscription.active).Exempel på payload
Event Types
Event Payloads
Handle Payment Failures
payment.failed och återställ nekade betalningarTesta webhooks
Skicka en exempelhändelse
Testa din webhook-integration direkt från dashboarden:Navigate to Webhooks
Open Testing Tab
Send Example
Check Your Endpoint
2xx-statuskod.Implementeringsexempel
Fullständig Express.js-implementation med webhook-verifiering och hantering:Testa webhooks med CLI
Dodo Payments CLI har två kommandon för att testa webhooks under lokal utveckling.Lyssna efter live-webhooks lokalt
Vidarebefordra verkliga webhook-händelser från ditt testlägeskonto till din lokala utvecklingsserver:http://localhost:3000/webhook) och bevarar alla headers för testning av signaturverifiering.
dodo login och välj Test Mode först.Utlös simulerade webhook-händelser
Skicka simulerade webhook-payloads till valfri endpoint utan att skapa riktiga transaktioner:subscription.past_due eller subscription.unpaused. Se Supported Webhook Events för den exakta listan.
CLI Webhook Testing Docs
Avancerade inställningar
Fliken Advanced innehåller ytterligare konfigurationsalternativ för finjustering av webhook-endpointens beteende.Hastighetsbegränsning (throttling)
Styr hastigheten med vilken webhook-händelser levereras till din endpoint. Som standard har webhooks ingen hastighetsbegränsning och händelser levereras så snart de inträffar.Open Advanced Tab
Configure Rate Limit
Set Your Limit
Anpassade headers
Lägg till anpassade HTTP-headers i alla webhook-requests som skickas till din endpoint. Användbart för autentisering, routing eller för att lägga till metadata.Add Headers
Add Multiple Headers
Transformationer
Med transformationer kan du ändra en webhooks payload och valfritt omdirigera den till en annan URL. Använd transformationer för att:- Ändra payload-strukturen före bearbetning
- Routa webhooks till olika endpoints baserat på innehåll
- Lägga till eller ta bort fält från payloaden
- Transformera dataformat
Enable Transformations
Configure Transformation
handler().Test Transformation
Övervaka webhook-loggar
Fliken Logs ger insyn i statusen för dina webhook-leveranser.Navigate to Logs Tab
Browse Delivery History
Search and Filter
View Message Details
- Den fullständiga webhook-payloaden
- Varje leveransförsök med svarskod och varaktighet
- Tidsstämpeln för varje försök
- Eventuella felmeddelanden från din endpoint
Aktivitetsövervakning
Gå till Developer → Webhooks och öppna fliken Activity för att se leveransprestanda för dina endpoints. Leveransaktivitet visar försök över tid, grupperade som Attempts per 5 minutes, Attempts per hour eller Attempts per day beroende på tidsfönstret. Varje stapel delas upp efter resultat och när du håller muspekaren över ett segment visas status, antalet försök och dess andel av totalen. På en endpoint sammanfattar Delivery stats (last 24h) på fliken Overview samma information för det senaste dygnet.Spela upp och återställ meddelanden
Hur du skickar ett meddelande igen beror på hur många meddelanden du behöver skicka:- Ett meddelande — öppna det från fliken Logs och använd åtgärden Replay på försöket.
- Ett intervall med meddelanden — öppna endpointen, eftersom masslägena endast gäller en endpoint åt gången.
Massuppspelning
Öppna endpointen från Developer → Webhooks. Tre lägen är tillgängliga och vart och ett gäller endast den endpointen:Open More Actions
Set the Range
Start the Run