Webhook-problemen oplossen

Hieronder vind je veelvoorkomende webhook-problemen en hoe je ze oplost.

Signatuurverificatie mislukt

De ruwe payload-body wordt niet gebruikt

Probleem: Bij het genereren van de signatuur gebruiken we de ruwe stringinhoud van de payload. Als je de JSON parseert en daarna weer stringifyt, komt de signatuur niet overeen. Oplossing: Gebruik altijd de ruwe request-body precies zoals ontvangen:

// WRONG - parsing and re-stringifying changes the format
const payload = JSON.parse(body);
verify(JSON.stringify(payload), headers); // Will fail!

// CORRECT - use the raw body
verify(rawBody, headers);

Verkeerde secret key

Probleem: De verkeerde webhook-secret gebruiken of deze niet correct decoderen. Oplossing:

Zorg dat je de juiste secret per endpoint gebruikt (secrets zijn uniek per endpoint)
Verwijder de whsec_-prefix vóór het base64-decoderen

Timestamp verlopen

Probleem: De klok van je server loopt uit de pas, waardoor geldige webhooks worden afgewezen. Oplossing: Zorg dat de tijd op je server is gesynchroniseerd via NTP.

Webhooks worden niet ontvangen

Endpoint niet bereikbaar

Probleem: Je endpoint is niet publiek bereikbaar. Oplossing:

Zorg dat je server draait en dat de endpoint-URL correct is
Controleer of firewallregels inkomende HTTPS-verzoeken toestaan
Verifieer dat het endpoint werkt met een simpele curl-test

SSL/TLS-problemen

Probleem: Ongeldig of verlopen SSL-certificaat. Oplossing: Zorg dat je endpoint een geldig SSL-certificaat van een vertrouwde CA heeft.

Verkeerde responsecodes

Foutcodes teruggeven bij succesvolle verwerking

Probleem: Niet-2xx-statuscodes teruggeven, ook als de webhook succesvol is verwerkt. Oplossing: Geef altijd een 2xx-statuscode terug zodra je de webhook succesvol hebt ontvangen en voor verwerking in de wachtrij hebt gezet:

// CORRECT
app.post('/webhooks', (req, res) => {
  queue.add(req.body); // Add to queue for async processing
  res.status(200).send('OK'); // Acknowledge immediately
});

Timeouts

Verwerking duurt te lang

Probleem: Je endpoint doet er langer dan 15 seconden over om te reageren. Oplossing: Verwerk webhooks asynchroon:

app.post('/webhooks', async (req, res) => {
  // Don't do this - blocks the response
  // await processOrder(req.body);
  
  // Do this instead - queue for background processing
  await queue.add('process-webhook', req.body);
  res.status(200).send('OK');
});

Herstellen na mislukking

Uitgeschakeld endpoint weer inschakelen

Als je endpoint na opeenvolgende mislukkingen is uitgeschakeld:

Verhelp de onderliggende oorzaak
Ga naar Settings → Developers → Manage Webhooks in het dashboard
Schakel het uitgeschakelde endpoint weer in in het ingebedde webhookportaal

Mislukte berichten opnieuw afspelen

Om gemiste webhooks na een storing terug te halen:

Ga naar de details van je endpoint
Klik op Options > Recover Failed Messages
Kies het tijdsbereik dat je opnieuw wilt afspelen

Bekijk de webhook-logs in je dashboard voor gedetailleerde foutmeldingen en responsecodes van je endpoint.

​Signatuurverificatie mislukt

​De ruwe payload-body wordt niet gebruikt

​Verkeerde secret key

​Timestamp verlopen

​Webhooks worden niet ontvangen

​Endpoint niet bereikbaar

​SSL/TLS-problemen

​Verkeerde responsecodes

​Foutcodes teruggeven bij succesvolle verwerking

​Timeouts

​Verwerking duurt te lang

​Herstellen na mislukking

​Uitgeschakeld endpoint weer inschakelen

​Mislukte berichten opnieuw afspelen

Signatuurverificatie mislukt

De ruwe payload-body wordt niet gebruikt

Verkeerde secret key

Timestamp verlopen

Webhooks worden niet ontvangen

Endpoint niet bereikbaar

SSL/TLS-problemen

Verkeerde responsecodes

Foutcodes teruggeven bij succesvolle verwerking

Timeouts

Verwerking duurt te lang

Herstellen na mislukking

Uitgeschakeld endpoint weer inschakelen

Mislukte berichten opnieuw afspelen