Hoppa till huvudinnehåll
Webhook-omslagsbild
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-implementering följer Standard Webhooks specifikation, vilket säkerställer kompatibilitet med branschens bästa praxis och befintliga webhook-bibliotek.

Nyckelfunktioner

Real-time Delivery

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

Secure by Default

HMAC SHA256-signaturverifiering ingår

Automatic Retries

Inbyggd omförsökslogik med exponentiell backoff

Event Filtering

Prenumerera endast på de händelser du behöver

Komma igång

1

Access Webhook Settings

Navigera till DodoPayments-instrumentpanelen och gå till Settings > Webhooks.
2

Create Webhook Endpoint

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

Add Endpoint URL

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

Select Events to Receive

Välj vilka specifika händelser din webhook-endpoint ska lyssna på genom att markera dem i händelselistan.
Endast valda händelser kommer att avlösa webhooks till din endpoint, vilket hjälper dig undvika onödig trafik och bearbetning.
5

Get Secret Key

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

Rotate Secret (Optional)

Vid behov kan du rotera din webhook-hemlighet för ökad säkerhet. Klicka på Rotate Secret-knappen i dina webhook-inställningar.
Att rotera hemligheten kommer att ogiltigförklara den och ersätta den med en ny. Den gamla hemligheten är endast giltig de nästa 24 timmarna. Därefter kommer verifiering med den gamla hemligheten att misslyckas.
Använd hemlighetsrotation regelbundet eller omedelbart om du misstänker att den nuvarande hemligheten har komprometterats.

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

Navigate to Webhook Details

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

Select Your Endpoint

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

Open Event Settings

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

Hantera händelseprenumerationer

1

View Available Events

Gränssnittet visar alla tillgängliga webhook-händelser organiserade hierarkiskt. Händelser är grupperade efter kategori (t.ex., dispute, payment, subscription).
2

Search and Filter

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

Select Events

Kryssa i rutorna bredvid de händelser du vill ta emot. Du kan:
  • Välja individuella underhändelser (t.ex., dispute.accepted, dispute.challenged)
  • Välja överordnade händelser för att ta emot alla relaterade underhändelser
  • Kombinera och matcha specifika händelser efter dina behov
4

Review Event Details

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

Save Configuration

Klicka på Save för att tillämpa dina ändringar, eller Cancel för att avbryta dem.
Om du avmarkerar alla händelser kommer din webhook-endpoint inte att ta emot några aviseringar. Se till att välja åtminstone de händelser 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.
Hantera webhooks asynkront genom att bekräfta mottagandet omedelbart med en 200-statuskod och därefter utföra 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
Max 8 omförsök per webhook-händelse. Till exempel, om en webhook misslyckas tre gånger innan den lyckas, är den totala leveranstiden ungefär 35 minuter och 5 sekunder från första försöket.
Använd Dodo Payments-instrumentpanelen för att manuellt omförsöka enskilda meddelanden eller återställa alla misslyckade meddelanden när som helst.

Idempotens

Each webhook event includes a unique webhook-id header. Use this identifier to implement idempotency and prevent duplicate processing.
// 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 ta emot 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 ta emot den senaste nyttolasten vid leveranstillfället, oavsett när webhook-händelsen ursprungligen skickades.

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

Each webhook request includes a webhook-signature header, an HMAC SHA256 signature of the webhook payload and timestamp, signed with your secret key.

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(): Tolkar payloads 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. Skapa det signerade meddelandet genom att sammanfoga webhook-id, webhook-timestamp och den exakt råa strängifierade payload, separerade med punkter (.).
  2. Beräkna HMAC SHA256 av den strängen med din webhook-hemliga nyckel från instrumentpanelen.
  3. Jämför den beräknade signaturen med webhook-signature-headern. Om de matchar är webhooken autentisk.
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 eventuella nyttolastformat, se Webhook Payload.

Svara på Webhooks

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

Bästa praxis

Använd alltid HTTPS-URL:er för webhook-endpoints. HTTP-endpoints är sårbara för man-in-the-middle-attacker och exponerar dina webhook-data.
Returnera en 200-statuskod omedelbart när du tar emot webhooken. Bearbeta händelsen asynkront för att undvika timeout.
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 hjälp av webhook-id-headern för att säkert bearbeta samma händelse flera gånger utan bieffekter.
Förvara din webhook-hemlighet säkert med miljövariabler eller en hemlighetshanterare. Lägg aldrig in hemligheter i 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
Unikt identifierare för denna webhook-händelse. Använd den 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-affärsidentifierare.
type
string
obligatorisk
Händelsetyp som utlöste denna webhook (t.ex. payment.succeeded, subscription.active).
timestamp
string
obligatorisk
ISO 8601-formaterad tidsstämpel för när händelsen inträffade.
data
object
obligatorisk
Händelsespecifik nyttolast 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.
Detaljer om endpoint

Åtkomst till testgränssnittet

1

Navigate to Webhooks

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

Select Your Endpoint

Klicka på din webhook-endpoint för att komma åt dess detaljsida.
3

Open Testing Tab

Klicka på fliken Testing för att öppna gränssnittet för webhook-testning.

Testa din Webhook

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

Select Event Type

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

Review Schema and Example

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

Send Test Event

Klicka på knappen Send Example för att skicka en testwebhook till din endpoint.
Viktigt: Misslyckade meddelanden som skickas via testgränssnittet kommer inte att försöka skickas om. Detta är endast för teständamål.

Verifiera ditt test

1

Check Your Endpoint

Övervaka dina webhook-endpoint-loggar för att bekräfta att testhändelsen mottogs.
2

Verify Signature

Se till att din signaturverifiering fungerar korrekt med testpayloaden.
3

Test Response

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.active':
      await handleSubscriptionActive(data);
      break;
    // Add more event handlers...
  }
}
Testa din webhook-hanterare grundligt med hjälp av testgränssnittet i instrumentpanelen innan du bearbetar produktionshändelser. Det hjälper dig identifiera och åtgärda problem i ett tidigt skede.

Testa webhooks med CLI

Dodo Payments CLI erbjuder två kommandon för att testa webhooks under lokal utveckling utan att lämna terminalen.

Lyssna på live-webhooks lokalt

Vidaredirigera riktiga webhook-händelser från ditt testläge-konto till din lokala utvecklingsserver i realtid:
dodo wh listen
CLI öppnar en WebSocket-anslutning till Dodo Payments och vidarebefordrar varje webhook-händelse till din lokala endpoint (t.ex., http://localhost:3000/webhook), samtidigt som alla headers behålls, inklusive signaturheaders för verifieringstestning.
Lyssnaren fungerar endast med API-nycklar för testläge. Kör dodo login och välj Test Mode innan du använder detta kommando.

Utlös mock-webhook-händelser

Skicka mockade webhook-payloads till valfri endpoint utan att skapa riktiga transaktioner:
dodo wh trigger
Detta interaktiva verktyg låter dig välja bland alla 22 stödda händelsetyper och skickar realistiska mockade payloads till din endpoint. Det loopar så att du kan testa flera händelser under en session.
Mockade webhook-payloads från dodo wh trigger är inte signerade. Använd unsafe_unwrap() istället för unwrap() i din webhook-hanterare endast under testning.

CLI Webhook Testing Docs

Se den fullständiga CLI-dokumentationen för webhook-testning

Avancerade inställningar

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

Hastighetsbegränsning (throttling)

Kontrollera takten som webhook-händelser levereras till din endpoint för att förhindra att systemet överbelastas.
1

Access Rate Limit Settings

I fliken Advanced, leta reda på avsnittet “Rate Limit (throttling)”.
2

Configure Rate Limit

Klicka på Edit-knappen för att ändra inställningarna för hastighetsbegränsning.
Som standard har webhooks “No rate limit” aktiverat, vilket innebär att händelser levereras så fort de inträffar.
3

Set Limits

Konfigurera önskad hastighetsbegränsning för att styra frekvensen på webhook-leveranser och undvika ö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 egna HTTP-headers i alla webhook-förfrågningar som skickas till din endpoint. Detta är användbart för autentisering, routning eller för att lägga till metadata i dina webhook-förfrågningar.
1

Add Custom Header

I avsnittet “Custom Headers” anger du en Key och ett Value för din anpassade header.
2

Add Multiple Headers

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

Save Configuration

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

Transformationer

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

Enable Transformations

Växla på Enabled-knappen för att aktivera transformationer.
2

Configure Transformation

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

Test Transformation

Använd testgränssnittet för att verifiera att din transformation fungerar korrekt innan du går live.
Transformationer kan ha stor påverkan på prestanda för webhook-leveranser. 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
  • Att lägga till beräknade fält till payloaden
  • Att routa händelser till olika mikrotjänster

Övervaka webhook-loggar

Fliken Logs ger omfattande insyn i statusen för dina webhook-leveranser, så att du kan övervaka, felsöka och hantera webhook-händelser effektivt.
Loggar

Aktivitetsövervakning

Fliken Activity ger realtidsinsikter i hur dina webhook-leveranser presterar med visuella analyser.
Aktivitet

E-postaviseringar

Håll dig informerad om webhook-hälsan med automatiska e-postaviseringar. När webhook-leveranser börjar misslyckas eller din endpoint slutar svara får du aviseringar så att du snabbt kan åtgärda problemen och hålla integrationerna igång smidigt.
Webhook-varningsinställningar som visar konfiguration för e-postaviseringar

Aktivera e-postaviseringar

1

Navigate to Alerting Settings

Gå till din Dodo Payments-instrumentpanel och navigera till Dashboard → Webhooks → Alerting.
2

Enable Email Notifications

Aktivera Email notifications för att börja ta emot aviseringar om problem med webhook-leveranser.
3

Configure Email Address

Ange den e-postadress dit du vill få webhook-aviseringar. Vi skickar notifikationer till den här adressen när vissa händelser inträffar i din webhook-setup, till exempel leveransproblem som kan påverka dina integrationer.
Aktivera e-postaviseringar för att fånga upp problem med webhook-leveranser tidigt och säkerställa pålitliga integrationer. Du får aviseringar när leveranser misslyckas eller när din endpoint slutar svara.

Distribuera till molnplattformar

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