Hoppa till huvudinnehåll
Webhook Cover Image
Webhooks ger realtidsnotifikationer när specifika händelser inträffar i ditt Dodo Payments-konto. Använd webhooks för att automatisera arbetsflöden, uppdatera din databas, skicka notifikationer och hålla dina system synkroniserade.
Vår webhook-implementation följer Standard Webhooks specifikationen, vilket säkerställer kompatibilitet med branschens bästa praxis och befintliga webhook-bibliotek.

Nyckelfunktioner

Realtidsleverans

Ta emot omedelbara notifikationer när händelser inträffar

Säker som standard

HMAC SHA256 signaturverifiering ingår

Automatiska omförsök

Inbyggd omförsökslogik med exponentiell backoff

Händelsefiltering

Prenumerera endast på händelser du behöver

Komma igång

1

Åtkomst till Webhook-inställningar

Navigera till DodoPayments Dashboard och gå till Settings > Webhooks.
2

Skapa Webhook Endpoint

Klicka på Add Webhook för att skapa en ny webhook-endpoint.
Lägg till Webhook
3

Lägg till Endpoint-URL

Ange URL:en där du vill ta emot webhook-händelser.
4

Välj händelser att ta emot

Välj de specifika händelser som din webhook-endpoint ska lyssna på genom att välja dem från händelselistan.
Endast valda händelser kommer att utlösa webhooks till din endpoint, vilket hjälper dig att undvika onödig trafik och bearbetning.
5

Hämta hemlig nyckel

Hämta din webhook Secret Key från inställningssidan. Du kommer att använda detta för att verifiera äktheten av mottagna webhooks.
Håll din webhook hemliga nyckel säker och exponera den aldrig i klientkod eller offentliga arkiv.
6

Rotera hemlig (valfritt)

Om det behövs kan du rotera din webhook-hemlighet för ökad säkerhet. Klicka på Rotera hemlig-knappen i dina webhook-inställningar.
Att rotera hemligheten kommer att utlöpa den och ersätta den med en ny. Den gamla hemligheten kommer endast att vara giltig under de kommande 24 timmarna. Efter det kommer försök att verifiera med den gamla hemligheten att misslyckas.
Använd hemlig rotation periodiskt eller omedelbart om du misstänker att din nuvarande hemlighet har blivit komprometterad.

Konfigurera prenumererade händelser

Du kan konfigurera vilka specifika händelser de vill ta emot för varje webhook-endpoint.

Åtkomst till händelsekonfiguration

1

Navigera till Webhook-detaljer

Gå till din Dodo Payments Dashboard och navigera till Settings > Webhooks.
2

Välj din endpoint

Klicka på den webhook-endpoint du vill konfigurera.
3

Öppna händelseinställningar

På sidan med webhook-detaljer ser du en sektion för “Prenumererade händelser”. Klicka på Redigera-knappen för att ändra dina händelseprenumerationer.

Hantera händelseprenumerationer

1

Visa tillgängliga händelser

Gränssnittet visar alla tillgängliga webhook-händelser organiserade i en hierarkisk struktur. Händelser grupperas efter kategori (t.ex. dispute, payment, subscription).
2

Sök och filtrera

Använd sökfältet för att snabbt hitta specifika händelser genom att skriva händelsenamn eller nyckelord.
3

Välj händelser

Markera rutorna bredvid de händelser du vill ta emot. Du kan:
  • Välja individuella underhändelser (t.ex. dispute.accepted, dispute.challenged)
  • Välja förälderhändelser för att ta emot alla relaterade underhändelser
  • Blanda och matcha specifika händelser baserat på dina behov
4

Granska händelsedetaljer

Hovra över informationsikonen (ⓘ) bredvid varje händelse för att se en beskrivning av när den händelsen utlöses.
5

Spara konfiguration

Klicka på Spara för att tillämpa dina ändringar, eller Avbryt för att avvisa modifieringar.
Om du avmarkerar alla händelser kommer din webhook-endpoint inte att ta emot några notifikationer. Se till att välja minst de händelser som din applikation behöver för att fungera korrekt.

Webhook-leverans

Tidsgränser

Webhooks har en 15-sekunders tidsgräns för både anslutnings- och läsningsoperationer. Se till att din endpoint svarar snabbt för att undvika tidsgränser.
Bearbeta webhooks asynkront genom att omedelbart bekräfta mottagandet med en 200 statuskod, och hantera den faktiska bearbetningen i bakgrunden.

Automatiska omförsök

Om en webhook-leverans misslyckas, försöker Dodo Payments automatiskt igen med exponentiell backoff för att förhindra att ditt system överbelastas.
FörsökFördröjningBeskrivning
1OmedelbartFörsta omförsöket sker direkt
25 sekunderAndra försöket efter kort fördröjning
35 minuterTredje försöket med ökad backoff
430 minuterFjärde försöket fortsätter backoff
52 timmarFemte försöket med förlängd fördröjning
65 timmarSjätte försöket med längre fördröjning
710 timmarSjunde försöket med maximal fördröjning
810 timmarSista försöket - webhook markerad som misslyckad om den misslyckas
Maximalt 8 omförsök per webhook-händelse. Till exempel, om en webhook misslyckas tre gånger innan den lyckas, är den totala leveranstiden cirka 35 minuter och 5 sekunder från det första försöket.
Använd Dodo Payments-dashboarden för att manuellt försöka om individuella meddelanden eller återhämta alla misslyckade meddelanden i bulk när som helst.

Idempotens

Varje webhook-händelse inkluderar en unik webhook-id header. Använd denna identifierare för att implementera idempotens och förhindra duplicerad bearbetning.
// Example: Storing webhook IDs to prevent duplicate processing
const processedWebhooks = new Set();

app.post('/webhook', (req, res) => {
  const webhookId = req.headers['webhook-id'];
  
  if (processedWebhooks.has(webhookId)) {
    return res.status(200).json({ received: true });
  }
  
  processedWebhooks.add(webhookId);
  // Process the webhook...
});
Implementera alltid idempotenskontroller. På grund av omförsök kan du få samma händelse flera gånger.

Händelseordning

Webhook-händelser kan anlända i oordning på grund av omförsök eller nätverksförhållanden. Utforma ditt system för att hantera händelser i vilken sekvens som helst.
Du kommer att få den senaste payloaden vid leveranstidpunkten, oavsett när webhook-händelsen ursprungligen avges.

Säkerställa Webhooks

För att säkerställa säkerheten för dina webhooks, validera alltid payloadarna och använd HTTPS.

Verifiera signaturer

Varje webhook-förfrågan inkluderar en webhook-signature header, en HMAC SHA256 signatur av webhook-payloaden och tidsstämpeln, signerad med din hemliga nyckel.

SDK-verifiering (rekommenderas)

Alla officiella SDK:er inkluderar inbyggda hjälpmedel för att säkert validera och analysera inkommande webhooks. Två metoder finns tillgängliga:
  • unwrap(): Verifierar signaturer med din webhook-hemliga nyckel
  • unsafe_unwrap(): Analyserar payloadar utan verifiering
Ge din webhook-hemlighet via DODO_PAYMENTS_WEBHOOK_KEY när du initierar Dodo Payments-klienten.
import DodoPayments from 'dodopayments';
import express from 'express';

const app = express();
app.use(express.raw({ type: 'application/json' }));

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
});

app.post('/webhook', async (req, res) => {
  try {
    const unwrapped = client.webhooks.unwrap(req.body.toString(), {
      headers: {
        'webhook-id': req.headers['webhook-id'] as string,
        'webhook-signature': req.headers['webhook-signature'] as string,
        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
      },
    });
    res.json({ received: true });
  } catch (error) {
    res.status(401).json({ error: 'Invalid signature' });
  }
});

Manuell verifiering (alternativ)

Om du inte använder en SDK kan du verifiera signaturer själv enligt Standard Webhooks-specifikationen:
  1. Bygg det signerade meddelandet genom att sammanfoga webhook-id, webhook-timestamp, och den exakta råa strängifierade payload, separerade med punkter (.).
  2. Beräkna HMAC SHA256 av den strängen med din webhook-hemliga nyckel från Dashboard.
  3. Jämför den beräknade signaturen med webhook-signature header. Om de matchar är webhooken äkta.
Vi följer Standard Webhooks-specifikationen. Du kan använda deras bibliotek för att verifiera signaturer: https://github.com/standard-webhooks/standard-webhooks/tree/main/libraries. För händelsepayloadformat, se Webhook Payload.

Svara på Webhooks

  • Din webhook-hanterare måste returnera en 2xx status code för att bekräfta mottagandet av händelsen.
  • Alla andra svar kommer att behandlas som ett misslyckande, och webhooken kommer att försöka igen.

Bästa praxis

Använd alltid HTTPS-URL:er för webhook-endpointar. HTTP-endpointar är sårbara för man-in-the-middle-attacker och exponerar dina webhook-data.
Återvänd en 200 statuskod omedelbart vid mottagandet av webhooken. Bearbeta händelsen asynkront för att undvika tidsgränser.
app.post('/webhook', async (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processWebhookAsync(req.body).catch(console.error);
});
Implementera idempotens med webhook-id header för att säkert bearbeta samma händelse flera gånger utan bieffekter.
Lagra din webhook-hemlighet säkert med hjälp av miljövariabler eller en hemlighetsförvaltare. Kom aldrig ihåg hemligheter till versionskontroll.

Webhook Payload-struktur

Att förstå webhook payload-strukturen hjälper dig att analysera och bearbeta händelser korrekt.

Förfrågningsformat

POST /your-webhook-url
Content-Type: application/json

Headers

webhook-id
string
obligatorisk
Unik identifierare för denna webhook-händelse. Använd detta för idempotenskontroller.
webhook-signature
string
obligatorisk
HMAC SHA256 signatur för att verifiera webhookens äkthet.
webhook-timestamp
string
obligatorisk
Unix-tidsstämpel (i sekunder) när webhooken skickades.

Förfrågningskropp

business_id
string
obligatorisk
Ditt Dodo Payments företagsidentifierare.
type
string
obligatorisk
Händelsetyp som utlöste denna webhook (t.ex. payment.succeeded, subscription.created).
timestamp
string
obligatorisk
ISO 8601 formaterad tidsstämpel för när händelsen inträffade.
data
object
obligatorisk
Händelsespecifik payload som innehåller detaljerad information om händelsen.

Exempel på Payload

{
  "business_id": "string",
  "type": "payment.succeeded | payment.failed |...",
  "timestamp": "2024-01-01T12:00:00Z",
  "data": {
    "payload_type": "Payment | Subscription | Refund | Dispute | LicenseKey",
    // ... event-specific fields (see below)
  }
}

Testa Webhooks

Du kan testa din webhook-integration direkt från Dodo Payments-dashboarden för att säkerställa att din endpoint fungerar korrekt innan du går live.
Endpoint Details

Åtkomst till testgränssnittet

1

Navigera till Webhooks

Gå till din Dodo Payments Dashboard och navigera till Settings > Webhooks.
2

Välj din endpoint

Klicka på din webhook-endpoint för att få åtkomst till dess detaljsida.
3

Öppna testfliken

Klicka på Testning-fliken för att få åtkomst till webhook-testgränssnittet.

Testa din Webhook

Testgränssnittet ger ett omfattande sätt att testa din webhook-endpoint:
1

Välj händelsetyp

Använd rullgardinsmenyn för att välja den specifika händelsetyp du vill testa (t.ex. payment.succeeded, payment.failed, etc.).
Rullgardinsmenyn innehåller alla tillgängliga webhook-händelsetyper som din endpoint kan ta emot.
2

Granska schema och exempel

Gränssnittet visar både Schema (datastruktur) och Exempel (exempelpayload) för den valda händelsetypen.
3

Skicka test-händelse

Klicka på Skicka exempel-knappen för att skicka en test-webhook till din endpoint.
Viktigt: Misslyckade meddelanden som skickas genom testgränssnittet kommer inte att försöka igen. Detta är endast för teständamål.

Verifiera ditt test

1

Kontrollera din endpoint

Övervaka loggarna för din webhook-endpoint för att bekräfta att test-händelsen mottogs.
2

Verifiera signatur

Se till att din signaturverifiering fungerar korrekt med testpayloaden.
3

Testa svar

Bekräfta att din endpoint returnerar en 2xx statuskod för att bekräfta mottagandet.

Implementeringsexempel

Här är en komplett Express.js-implementering som visar webhook-verifiering och hantering:
import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
app.use(express.json());

const webhook = new Webhook(process.env.DODO_WEBHOOK_SECRET);

app.post('/webhook/dodo-payments', async (req, res) => {
  try {
    // Extract webhook headers
    const webhookHeaders = {
      "webhook-id": req.headers["webhook-id"] as string,
      "webhook-signature": req.headers["webhook-signature"] as string,
      "webhook-timestamp": req.headers["webhook-timestamp"] as string,
    };

    // Verify the webhook signature
    const payload = JSON.stringify(req.body);
    await webhook.verify(payload, webhookHeaders);
    
    // Acknowledge receipt immediately
    res.status(200).json({ received: true });
    
    // Process webhook asynchronously
    processWebhookAsync(req.body).catch(console.error);
    
  } catch (error) {
    console.error('Webhook verification failed:', error);
    res.status(400).json({ error: 'Invalid signature' });
  }
});

async function processWebhookAsync(data: any) {
  // Handle the webhook event based on type
  switch (data.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(data);
      break;
    case 'subscription.created':
      await handleSubscriptionCreated(data);
      break;
    // Add more event handlers...
  }
}
Testa din webhook-hanterare noggrant med hjälp av testgränssnittet på dashboarden innan du bearbetar produktionshändelser. Detta hjälper till att identifiera och åtgärda problem tidigt.

Avancerade inställningar

Fliken Avancerade inställningar ger ytterligare konfigurationsalternativ för att finjustera beteendet hos din webhook-endpoint.

Hastighetsbegränsning (Throttling)

Kontrollera hastigheten med vilken webhook-händelser levereras till din endpoint för att förhindra att ditt system överbelastas.
1

Åtkomst till inställningar för hastighetsbegränsning

I fliken Avancerat, lokalisera sektionen “Hastighetsbegränsning (throttling)”.
2

Konfigurera hastighetsbegränsning

Klicka på Redigera-knappen för att ändra inställningarna för hastighetsbegränsning.
Som standard har webhooks “Ingen hastighetsbegränsning” tillämpad, vilket innebär att händelser levereras så snart de inträffar.
3

Ställ in begränsningar

Konfigurera din önskade hastighetsbegränsning för att kontrollera frekvensen av webhook-leveranser och förhindra systemöverbelastning.
Använd hastighetsbegränsning när din webhook-hanterare behöver tid för att bearbeta händelser eller när du vill gruppera flera händelser tillsammans.

Anpassade headers

Lägg till anpassade HTTP-headers till alla webhook-förfrågningar som skickas till din endpoint. Detta är användbart för autentisering, routing eller för att lägga till metadata till dina webhook-förfrågningar.
1

Lägg till anpassad header

I sektionen “Anpassade headers”, ange en Nyckel och Värde för din anpassade header.
2

Lägg till flera headers

Klicka på +-knappen för att lägga till ytterligare anpassade headers vid behov.
3

Spara konfiguration

Dina anpassade headers kommer att inkluderas i alla webhook-förfrågningar till denna endpoint.

Transformationer

Transformationer gör att du kan modifiera en webhooks payload och omdirigera den till en annan URL. Denna kraftfulla funktion gör att du kan:
  • Modifiera payload-strukturen innan bearbetning
  • Rutta webhooks till olika endpointar baserat på innehåll
  • Lägga till eller ta bort fält från payloaden
  • Transformera dataformat
1

Aktivera transformationer

Växla Aktiverad-knappen för att aktivera transformationsfunktionen.
2

Konfigurera transformation

Klicka på Redigera transformation för att definiera dina transformationsregler.
Du kan använda JavaScript för att transformera webhook-payloaden och specificera en annan mål-URL.
3

Testa transformation

Använd testgränssnittet för att verifiera att din transformation fungerar korrekt innan du går live.
Transformationer kan påverka webhook-leveransens prestanda avsevärt. Testa noggrant och håll transformationslogiken enkel och effektiv.
Transformationer är särskilt användbara för:
  • Konvertering mellan olika dataformat
  • Filtrering av händelser baserat på specifika kriterier
  • Lägga till beräknade fält till payloaden
  • Rutta händelser till olika mikrotjänster

Övervakning av Webhook-loggar

Loggar-fliken ger omfattande insyn i din webhook-leveransstatus, vilket gör att du kan övervaka, felsöka och hantera webhook-händelser effektivt.
Loggar

Aktivitetsovervakning

Aktivitetsfliken ger realtidsinsikter i din webhook-leveransprestanda med visuell analys.
Aktivitet

E-postaviseringar

Håll dig informerad om din webhook-hälsa med automatiska e-postnotifikationer. När webhook-leveranser börjar misslyckas eller din endpoint slutar svara, får du e-postaviseringar så att du snabbt kan åtgärda problem och hålla dina integrationer igång smidigt.
Webhook Alerting Settings showing email notifications configuration

Aktivera e-postaviseringar

1

Navigera till inställningar för aviseringar

Gå till din Dodo Payments Dashboard och navigera till Dashboard → Webhooks → Aviseringar.
2

Aktivera e-postnotifikationer

Växla på E-postnotifikationer för att börja ta emot aviseringar om problem med webhook-leveranser.
3

Konfigurera e-postadress

Ange e-postadressen där du vill ta emot webhook-aviseringar. Vi skickar notifikationer till denna adress när vissa händelser inträffar med din webhook-konfiguration, såsom leveransproblem som kan påverka dina integrationer.
Aktivera e-postaviseringar för att fånga problem med webhook-leveranser tidigt och upprätthålla pålitliga integrationer. Du kommer att meddelas när leveranser misslyckas eller din endpoint blir oresponsiv.

Distribuera till molnplattformar

Redo att distribuera din webhook-hanterare till produktion? Vi tillhandahåller plattformsspecifika guider för att hjälpa dig att distribuera webhooks till populära molnleverantörer med bästa praxis för varje plattform.
Varje plattformsguide inkluderar miljöinställningar, signaturverifiering och distributionssteg specifika för den leverantören.