Webhooks configureren

Published: 16 juli 2026 · Last updated: 21 juli 2026 · By Marcus Biel

Met webhooks kan Maildroppa een andere applicatie op de hoogte stellen wanneer er iets belangrijks gebeurt in je account.

In plaats van Maildroppa herhaaldelijk te vragen of een abonnee is aangemaakt, bijgewerkt, uitgeschreven of een tag heeft gekregen, kan je applicatie kort nadat de gebeurtenis plaatsvindt een HTTPS-verzoek ontvangen.

De pagina Webhooks is de centrale plek voor deze accountbrede integratie. Je kunt meerdere endpoints aanmaken, kiezen welke gebeurtenissen elk endpoint ontvangt, authenticatieheaders toevoegen, de verbinding testen, bezorgpogingen bekijken en indien nodig een productiegebeurtenis opnieuw afspelen.

Hoe accountwebhooks werken

Een accountwebhook werkt als volgt:

1. Er vindt een gebeurtenis plaats in Maildroppa, bijvoorbeeld wanneer een abonnee wordt aangemaakt.
2. Maildroppa zoekt elk actief endpoint dat op die gebeurtenis is geabonneerd.
3. Maildroppa maakt één bezorging aan voor elk overeenkomend endpoint.
4. De JSON-payload wordt ondertekend met het Signing secret van je account voor webhooks.
5. Maildroppa stuurt een HTTPS POST-verzoek naar de opgeslagen endpoint-URL.
6. Je endpoint verifieert de handtekening, slaat de gebeurtenis op of verwerkt deze en retourneert een HTTP-respons.
7. Maildroppa registreert het resultaat in de bezorggeschiedenis en probeert tijdelijke fouten automatisch opnieuw.

Als meerdere endpoints op dezelfde gebeurtenis zijn geabonneerd, ontvangt elk endpoint zijn eigen bezorging. De bedrijfsmatige gebeurtenis heeft voor alle endpoints dezelfde Event ID, terwijl elke bezorging een eigen Delivery ID heeft.

Accountwebhooks verschillen van een stap “Send a webhook” binnen een Automation. Accountwebhooks luisteren naar geselecteerde accountgebeurtenissen in heel Maildroppa. Een Automation-webhook wordt alleen verzonden wanneer een abonnee die specifieke stap bereikt. Beide gebruiken het Signing secret voor webhooks van het account, dus het roteren van het secret heeft gevolgen voor elke uitgaande webhook-ontvanger die Maildroppa-handtekeningen verifieert.

De pagina Webhooks openen

Open “Settings”, vouw “Developers” uit en selecteer “Webhooks”.

De pagina bevat drie hoofdonderdelen:

• Signing secret
• Endpoints
• Bezorggeschiedenis voor het geselecteerde endpoint

Als je meer dan één endpoint hebt, selecteer je een endpointregel om de bezorggeschiedenis weer te geven. Als je niet expliciet een endpoint hebt geselecteerd, toont Maildroppa de geschiedenis van het eerste endpoint in de lijst.

Voordat je een endpoint aanmaakt

Bereid een ontvanger op je server voor voordat je Maildroppa configureert. De ontvanger moet:

• Beschikbaar zijn via een openbare HTTPS-URL.
• POST-verzoeken met een application/json-body accepteren.
• De onbewerkte requestbody bewaren totdat de Maildroppa-handtekening is geverifieerd.
• Alleen een 2xx-status retourneren nadat de gebeurtenis veilig is geaccepteerd.
• Herhaalde bezorgingen idempotent verwerken met behulp van de Event ID.
• Snel reageren in plaats van tijdens het verzoek traag werk uit te voeren.

Een betrouwbaar patroon is om het verzoek te verifiëren, de Event ID en payload op te slaan in een duurzame wachtrij of database, 200 of 204 te retourneren en de bedrijfsactie daarna te verwerken.

Stel geen ontwikkelcomputer, lokaal netwerkadres of onbeveiligd script bloot als productie-webhookontvanger. Maildroppa accepteert alleen openbare HTTPS-doelen en controleert de bestemming opnieuw wanneer een bezorging wordt verzonden.

Stap 1: het Signing secret genereren

Elk Maildroppa-webhookverzoek wordt ondertekend. Je ontvanger gebruikt het Signing secret om te verifiëren dat het verzoek door Maildroppa is aangemaakt en dat de body tijdens het transport niet is gewijzigd.

Bovenaan de pagina toont het paneel Signing secret een van deze statussen:

• Missing — Er bestaat nog geen Signing secret.
• Ready — Er is een Signing secret geconfigureerd.
• Loading — Maildroppa haalt de huidige status op.

Klik op “Generate secret” wanneer de status Missing is.

Maildroppa toont het nieuwe secret onmiddellijk. Het begint met whsec_. Klik op “Copy” en bewaar het in de secretmanager of beschermde omgevingsconfiguratie die je ontvanger gebruikt.

De volledige waarde wordt alleen onmiddellijk na het genereren of roteren getoond. Wanneer je de pagina opnieuw laadt of verlaat, toont Maildroppa alleen dat er een secret bestaat en wanneer dit voor het laatst is bijgewerkt. Het opgeslagen secret wordt niet opnieuw onthuld.

Als je het secret kwijtraakt

Als de ontvanger het huidige secret niet meer heeft, klik je op “Rotate secret” en sla je de nieuw weergegeven waarde op.

Rotatie vervangt het vorige secret onmiddellijk. Maildroppa bewaart beide waarden niet gedurende een overgangsperiode. Werk elke ontvanger die dit accountsecret gebruikt bij voordat je verdere tests uitvoert of op productieleveringen vertrouwt.

Nieuwe bezorgingen, geplande nieuwe pogingen, tests en replays worden ondertekend met het huidige secret op het moment dat het HTTP-verzoek wordt uitgevoerd. Dit betekent dat een bezorging die vóór de rotatie is aangemaakt, bij een latere poging alsnog met het nieuwe secret kan worden ondertekend.

Behandel het secret als een wachtwoord

Plaats het Signing secret niet in browsercode, een openbare repository, een URL, een foutpagina of een gewoon applicatielogboek.

Alleen de server-side ontvanger heeft het secret nodig. Als je denkt dat het is blootgesteld, roteer je het en werk je alle ontvangers onmiddellijk bij.

Een webhookhandtekening verifiëren

Elk verzoek bevat deze Maildroppa-headers:

• X-Maildroppa-Event-Id — Identificeert de bedrijfsmatige gebeurtenis.
• X-Maildroppa-Delivery-Id — Identificeert deze specifieke bezorging.
• X-Maildroppa-Timestamp — Het tijdstip van ondertekening als Unix-seconden.
• X-Maildroppa-Signature — De versiegebonden HMAC-handtekening.

Maildroppa stuurt ook:

• Content-Type: application/json
• User-Agent: Maildroppa-Webhooks/1.0

De handtekening heeft deze indeling:

v1=<lowercase hexadecimal HMAC>

Maildroppa maakt deze met HMAC-SHA256. De ondertekende inhoud bestaat uit de timestamp, gevolgd door een punt, gevolgd door de exact onbewerkte JSON-requestbody:

<timestamp>.<raw request body>

Gebruik het Signing secret als HMAC-sleutel.

Het volgende Node.js-voorbeeld toont de essentiële verificatiestap. rawBody moet de oorspronkelijke requestbytes bevatten, niet JSON die al is geparseerd en opnieuw geserialiseerd.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Vergelijk na het verifiëren van de handtekening ook de timestamp met de servertijd. Wijs verzoeken af die buiten een korte tolerantie vallen die je voor je infrastructuur hebt gekozen, bijvoorbeeld vijf minuten. Dit verkleint het risico dat een onderschept geldig verzoek veel later opnieuw wordt afgespeeld.

Parse en verwerk de JSON pas nadat beide controles zijn geslaagd.

Veelvoorkomende oorzaken van handtekeningfouten

Een handtekening mislukt meestal om een van deze redenen:

• De ontvanger gebruikt na een rotatie een oud secret.
• Middleware heeft de JSON geparsed of gewijzigd voordat de handtekening werd berekend.
• De ontvanger ondertekent alleen de body en laat <timestamp>. weg.
• De timestamp wordt behandeld als een opgemaakte datum in plaats van als de exacte headerwaarde.
• Het voorvoegsel v1= ontbreekt in de vergelijking.
• De berekende HMAC is anders gecodeerd in plaats van als hexadecimaal in kleine letters.

Log de Event ID en Delivery ID wanneer de verificatie mislukt, maar log nooit het Signing secret of gevoelige waarden van aangepaste headers.

Stap 2: een endpoint toevoegen

Klik in het gedeelte Endpoints op “Add endpoint”.

De editor bevat vier onderdelen:

• Endpoint URL
• Events
• Custom headers
• Active status

Nieuwe endpoints beginnen als Active en alle gebeurtenissen die in de editor worden getoond, zijn aanvankelijk geselecteerd. Controleer de selectie voordat je opslaat, zodat de ontvanger alleen de meldingen krijgt die hij daadwerkelijk nodig heeft.

De endpoint-URL configureren

Voer de volledige openbare URL in die Maildroppa-verzoeken moet ontvangen, bijvoorbeeld:

https://integrations.example.com/webhooks/maildroppa

De URL moet aan deze vereisten voldoen:

• De URL moet https:// gebruiken.
• De URL moet een geldige openbare hostnaam bevatten.
• De URL mag maximaal 2.048 tekens lang zijn.
• De URL mag geen templatevariabelen met { of } bevatten.
• De URL mag geen gebruikersnaam of wachtwoord vóór de hostnaam bevatten.
• De URL mag geen URL-fragment bevatten dat begint met #.
• De URL moet de standaard HTTPS-poort 443 gebruiken.
• De URL mag geen localhost, onbewerkt IP-adres of hostnaam gebruiken die verwijst naar een geblokkeerd privé- of gereserveerd netwerk.

Queryparameters worden ondersteund, maar plaats geen API-sleutels of andere secrets in de URL. URL’s zijn zichtbaar in de endpointlijst en bezorggegevens. Gebruik in plaats daarvan een Custom header voor aanmeldgegevens.

Maildroppa volgt geen redirects. Sla de uiteindelijke HTTPS-bestemming op in plaats van een URL die 301, 302, 307 of 308 retourneert.

De hostnaam van de bestemming wordt opnieuw opgelost voordat het verzoek wordt verzonden. Een hostnaam die later naar een privé- of geblokkeerd adres verwijst, wordt afgewezen, zelfs als deze geldig was toen het endpoint werd opgeslagen.

Gebeurtenissen kiezen

Selecteer ten minste één gebeurtenis. Een endpoint ontvangt alleen de gebeurtenistypen die in de editor zijn geselecteerd.

De pagina biedt deze gebeurteniskeuzes:

Subscriber Created — subscriber.created

Wordt verzonden wanneer een abonnee in het Maildroppa-account wordt aangemaakt.

Gebruik deze gebeurtenis om het overeenkomstige contact aan te maken in een CRM, customer data platform, interne database of ander systeem waarin rekening wordt gehouden met toestemming.

Interpreteer deze gebeurtenis niet als bewijs dat elke inschrijving Double Opt-in heeft voltooid. De abonnementsstatus in de payload beschrijft de huidige toestand.

Subscriber Updated — subscriber.updated

Wordt verzonden wanneer ingebouwde abonneegegevens of waarden van aangepaste velden veranderen.

Gebruik het volledige abonneeobject in de payload als de huidige Maildroppa-weergave. Ga er niet van uit dat slechts één bepaalde eigenschap is gewijzigd.

Toewijzingen en verwijderingen van tags hebben hun eigen gebeurtenistypen, zodat ze afzonderlijk kunnen worden verwerkt.

Subscriber Unsubscribed — subscriber.unsubscribed

Wordt verzonden wanneer de abonnee door een uitschrijfactie naar de status uitgeschreven gaat.

Gebruik deze gebeurtenis om het contact in verbonden systemen te onderdrukken. Schrijf de persoon niet automatisch opnieuw in omdat een ander systeem het contact nog als actief markeert.

Tag Added — subscriber.tag_added

Wordt verzonden wanneer een tag aan een abonnee wordt toegewezen.

De payload bevat de abonnee en de tag die bij deze specifieke wijziging betrokken zijn.

Tag Removed — subscriber.tag_removed

Wordt verzonden wanneer een tag bij een abonnee wordt verwijderd.

De payload bevat de bijgewerkte abonnee en de verwijderde tag. De verwijderde tag wordt afzonderlijk meegegeven, ook al staat deze niet meer in de huidige tags-array van de abonnee.

Form Submitted — form.submitted

Wordt verzonden wanneer een bezoeker een Maildroppa-inschrijfformulier indient.

Behandel dit als een signaal dat een formulier is ingediend, niet als bevestiging dat Double Opt-in is voltooid. Elke workflow die een bevestigde inschrijving vereist, moet rekening blijven houden met de huidige status van de abonnee en het bevestigingsproces.

Gebruik afzonderlijke endpoints wanneer verantwoordelijkheden verschillen

Je kunt verschillende gebeurtenissen naar verschillende systemen sturen. Bijvoorbeeld:

• Stuur abonnee- en tagevenementen naar een CRM.
• Stuur uitschrijfevenementen naar een suppressieservice.
• Stuur formulierindieningsevents naar een analysekanaal.

Afzonderlijke endpoints verminderen onnodig verkeer en maken het eenvoudiger om fouten te diagnosticeren. Elk endpoint heeft een eigen gebeurteniskeuze, URL, aangepaste headers, actieve status, tests en bezorggeschiedenis.

Aangepaste headers toevoegen

Aangepaste headers zijn optioneel. Gebruik ze wanneer de ontvanger een API-sleutel, bearer-token, tenant-ID of een andere vaste header vereist.

Klik op “Add header” en voer vervolgens de Header name en Header value in. Geschikte voorbeelden zijn:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

Je kunt maximaal 20 aangepaste headers toevoegen.

Headernamen:

• Zijn verplicht.
• Mogen maximaal 128 tekens bevatten.
• Moeten geldige tekens voor HTTP-headernamen gebruiken.
• Moeten uniek zijn, ongeacht hoofdlettergebruik.

Headerwaarden:

• Zijn verplicht.
• Mogen maximaal 2.000 tekens bevatten.
• Mogen geen regeleinden bevatten.

De volgende namen zijn gereserveerd en kunnen niet worden vervangen door een aangepaste header:

• Content-Type
• Content-Length
• Host
• User-Agent
• Elke naam die begint met X-Maildroppa-

Dit voorkomt dat een aangepaste waarde de bezorgings- en signatureheaders van Maildroppa vervangt.

Hoe headersecrets worden opgeslagen

Maildroppa versleutelt waarden van aangepaste headers voordat ze worden opgeslagen. Opgeslagen waarden worden niet in leesbare vorm aan de browser teruggegeven.

Wanneer je het endpoint later bewerkt, toont het waardeveld “Stored value kept”. Laat dit leeg wanneer het bestaande secret ongewijzigd moet blijven. Voer een nieuwe waarde in om het te vervangen.

Als je de headernaam wijzigt, moet je de waarde opnieuw invoeren. Maildroppa bewaart een opgeslagen secret alleen zolang de oorspronkelijke headernaam ongewijzigd blijft.

Wanneer je een headerregel verwijdert, wordt die header na het opslaan van het endpoint uit toekomstige bezorgingen verwijderd.

Waarden van aangepaste headers worden in opgeslagen verzoekinformatie als gevoelig behandeld. Ze worden gemaskeerd in plaats van weergegeven in de bezorggeschiedenis.

Het endpoint activeren of deactiveren

Laat “Active” geselecteerd wanneer het endpoint onmiddellijk gebeurtenissen moet kunnen ontvangen.

Schakel dit uit wanneer je de configuratie wilt opslaan zonder bezorgingen te starten. Je kunt het endpoint later vanuit de endpointlijst activeren.

Een inactief endpoint:

• Ontvangt geen nieuw plaatsgevonden gebeurtenissen.
• Kan geen Test webhook verzenden.
• Blijft zichtbaar en bewerkbaar.
• Behoudt de bestaande bezorggeschiedenis.

Het activeren van een endpoint vult gebeurtenissen die plaatsvonden toen het inactief was niet met terugwerkende kracht aan.

Klik op “Save” wanneer de URL, gebeurteniskeuze, headers en status correct zijn.

De endpointlijst begrijpen

Elke endpointregel toont:

• De bestemmings-URL.
• Een Active- of Inactive-badge.
• De geabonneerde gebeurtenistypen.
• Het aantal aangepaste headers.
• Het tijdstip waarop het endpoint voor het laatst is bijgewerkt.

De beschikbare acties zijn:

• On/Off — Activeert of deactiveert het endpoint.
• Test — Verzendt één onmiddellijk testverzoek naar een actief endpoint.
• Edit — Wijzigt de URL, gebeurtenissen, headers of actieve status.
• Delete — Verwijdert de endpointconfiguratie permanent na bevestiging.

Selecteer het hoofdgedeelte van een regel om de bezorggeschiedenis van dat endpoint onder de lijst te openen.

Hoe opgeslagen wijzigingen bestaande bezorgingen beïnvloeden

Een accountgebeurtenis maakt een bezorging aan met een momentopname van de endpoint-URL, payload en aangepaste headers op dat moment.

Het bewerken van de URL of aangepaste headers heeft gevolgen voor nieuw aangemaakte bezorgingen. Een bezorging die al in de wachtrij staat, behoudt de oorspronkelijke bestemming en opgeslagen headerconfiguratie.

Het wijzigen van de geselecteerde gebeurtenissen heeft ook alleen gevolgen voor gebeurtenissen die daarna plaatsvinden. Maildroppa maakt niet met terugwerkende kracht bezorgingen aan voor gebeurtenistypen die niet waren geselecteerd toen de gebeurtenis plaatsvond.

Het Signing secret werkt anders: het wordt gelezen wanneer het HTTP-verzoek wordt voorbereid. Een in behandeling zijnde bezorging of replay kan daarom een nieuw geroteerd Signing secret gebruiken, ook wanneer de payload en momentopname van het endpoint eerder zijn aangemaakt.

Een endpoint testen

Klik op “Test” bij een actief endpoint nadat de ontvanger en het Signing secret klaar zijn.

Maildroppa verzendt onmiddellijk één ondertekend verzoek met de opgeslagen endpoint-URL en opgeslagen aangepaste headers. Niet-opgeslagen wijzigingen in een geopende editor maken geen deel uit van de test.

De testpayload gebruikt het gebeurtenistype webhook.test en stelt livemode in op false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

De gegenereerde ID’s en timestamp verschillen bij elke echte test.

Een test doet precies één HTTP-poging. Testbezorgingen worden niet opgenomen in het productieterugtestschema en kunnen niet opnieuw worden afgespeeld.

Nadat het verzoek is voltooid, toont het resultaatpaneel:

• Test success of Test failed
• Event ID
• HTTP-status, wanneer een respons is ontvangen
• Duur
• Delivery ID
• Foutinformatie, indien beschikbaar
• Een responsfragment, wanneer de ontvanger een body heeft teruggestuurd

De test verschijnt ook in de bezorggeschiedenis met een Test-badge. Gebruik het filter “Test” om alleen testverzoeken te tonen.

De productiepayload begrijpen

Productie-accountgebeurtenissen gebruiken een algemene JSON-envelop:

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

De eigenschappen op het hoogste niveau betekenen:

• id — De Event ID. Deze komt overeen met X-Maildroppa-Event-Id.
• type — De gebeurtenissleutel die in de endpointeditor is geselecteerd.
• schema_version — De versie van het payloadschema. Gebruik deze bij het bepalen hoe je de gebeurtenis parseert.
• created_at — Het tijdstip waarop de eventpayload is aangemaakt, in UTC.
• livemode — true voor productiegebeurtenissen en false voor testgebeurtenissen.
• data — De gebeurtenisspecifieke inhoud.

Routeer gebeurtenissen op basis van de exacte type-waarde. Negeer aanvullende eigenschappen die je integratie niet nodig heeft, zodat compatibele uitbreidingen van payloads de ontvanger niet verstoren.

Payload van abonneegebeurtenissen

Abonneegebeurtenissen bevatten de huidige weergave van de abonnee in data.subscriber:

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

fields en tags zijn arrays. Ze kunnen leeg zijn. Een abonnee-eigenschap kan ook null zijn wanneer er geen waarde bestaat. Je ontvanger moet daarom het payloadschema volgen en er niet van uitgaan dat elke optionele profielwaarde aanwezig is.

Payload van tagevenementen

Tagevenementen bevatten zowel de abonnee als de tag die de gebeurtenis heeft veroorzaakt:

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

Bij subscriber.tag_removed identificeert data.tag nog steeds de verwijderde tag, ook al bevat de huidige tags-array van de abonnee deze niet meer.

Event ID’s, Delivery ID’s en idempotentie

De Event ID en Delivery ID hebben verschillende functies.

Event ID

De Event ID identificeert de bedrijfsmatige gebeurtenis. Deze staat in:

• De eigenschap id op het hoogste niveau van de payload.
• De requestheader X-Maildroppa-Event-Id.
• De bezorggeschiedenis.

Dezelfde gebeurtenis kan naar meerdere geabonneerde endpoints worden verzonden. Die bezorgingen delen dezelfde Event ID.

Nieuwe pogingen en handmatige replays behouden ook de oorspronkelijke Event ID. Sla verwerkte Event ID’s op en maak de bedrijfsactie idempotent, zodat een herhaald verzoek geen dubbele contacten aanmaakt, een onomkeerbare actie herhaalt of dezelfde wijziging tweemaal toepast.

Delivery ID

De Delivery ID identificeert één bezorgingsrecord. Deze staat in:

• De requestheader X-Maildroppa-Delivery-Id.
• De bezorggeschiedenis.

Elke endpointbezorging heeft een eigen Delivery ID. Een handmatige replay maakt een nieuwe Delivery ID aan, maar behoudt de oorspronkelijke Event ID.

Gebruik de Delivery ID voor technische tracering en ondersteuning. Gebruik de Event ID voor deduplicatie op bedrijfsniveau.

De juiste HTTP-respons retourneren

Maildroppa classificeert responses als volgt:

• Elke 2xx-response markeert de bezorging als geslaagd.
• 408 Request Timeout, 429 Too Many Requests en 5xx-responses zijn tijdelijke fouten en kunnen opnieuw worden geprobeerd.
• Netwerkfouten die tijdelijk kunnen zijn, worden opnieuw geprobeerd.
• Redirects en andere 3xx-responses worden niet gevolgd en worden behandeld als definitieve fouten.
• Andere 4xx-responses worden behandeld als definitieve fouten en niet opnieuw geprobeerd.

Retourneer alleen 200, 202 of 204 wanneer de gebeurtenis veilig is geaccepteerd. Als verwerking tijd kost, sla de gebeurtenis dan eerst op en retourneer een succesrespons voordat je het tragere werk asynchroon uitvoert.

Retourneer geen redirect naar een andere webhook-URL. Configureer in plaats daarvan de definitieve URL in Maildroppa.

Automatisch schema voor nieuwe pogingen

Productiebezorgingen kunnen maximaal zeven HTTP-pogingen doen.

Na een fout waarvoor opnieuw proberen mogelijk is, plant Maildroppa de volgende poging met deze tussenpozen:

1. Na poging 1: 1 minuut
2. Na poging 2: 5 minuten
3. Na poging 3: 30 minuten
4. Na poging 4: 2 uur
5. Na poging 5: 12 uur
6. Na poging 6: 24 uur

Als poging 7 nog steeds een fout oplevert waarvoor opnieuw proberen mogelijk is, wordt de bezorging Dead en wordt er geen verdere automatische poging gepland.

Het schema wordt gemeten vanaf de afzonderlijke mislukte pogingen. De daadwerkelijke bezorgtijd kan iets later zijn omdat bezorgingen asynchroon worden verwerkt en ook onderhevig zijn aan systeemlimieten voor bescherming.

Los een tijdelijk probleem bij de ontvanger indien mogelijk op vóór het weergegeven tijdstip “Next retry”. Als de automatische pogingen zijn beëindigd, gebruik je Replay nadat de ontvanger weer beschikbaar is.

De bezorggeschiedenis begrijpen

De bezorggeschiedenis hoort bij het momenteel geselecteerde endpoint. De endpoint-URL staat in de kop van het gedeelte, zodat je kunt controleren welke geschiedenis je bekijkt.

Gebruik deze filters:

• All — Toont productie- en testbezorgingen.
• Production — Toont alleen live gebeurtenisbezorgingen.
• Test — Toont alleen handmatige tests.

Klik op “Refresh” om de nieuwste status op te halen. De geschiedenis hoeft niet geopend te blijven terwijl Maildroppa een bezorging verzendt of opnieuw probeert.

De pagina toont de 50 nieuwste overeenkomende bezorgingen voor het geselecteerde filter.

Kolommen in de bezorggeschiedenis

Elke regel bevat:

• Created — Wanneer het bezorgingsrecord is aangemaakt.
• State — Pending, Success, Failed of Dead.
• HTTP — Responsstatus, aantal pogingen, duur en de tijd van de volgende poging, indien van toepassing.
• Subscriber — Het e-mailadres van de abonnee wanneer de gebeurtenis aan een abonnee is gekoppeld.
• Delivery — Gebeurtenistype, Event ID en Delivery ID.
• Actions — Replay wanneer de bezorging daarvoor in aanmerking komt.

Als er geen HTTP-verzoek is gedaan, toont de HTTP-kolom “No HTTP attempt”. Dit kan gebeuren wanneer Maildroppa het verzoek afwijst voordat het wordt verzonden, bijvoorbeeld omdat het Signing secret ontbreekt of de opgeslagen bestemming niet langer veilig kan worden gebruikt.

Wanneer beschikbaar toont de regel ook een Error en een Response excerpt die door de ontvanger zijn teruggestuurd. Retourneer geen secrets of gevoelige persoonsgegevens in een webhook-responsbody, omdat een deel van die respons in het bezorgingslogboek van het account kan verschijnen.

Bezorgstatussen

Pending betekent dat de bezorging wacht op de eerste poging of een geplande nieuwe poging. “Next retry” verschijnt wanneer er een nieuwe poging is gepland.

Success betekent dat de ontvanger een 2xx-respons heeft geretourneerd. Er is geen verdere automatische poging nodig.

Failed betekent dat de bezorging is beëindigd door een niet-opnieuw-probeerbaar probleem, vóór een HTTP-poging is afgewezen of is gestopt voordat deze kon worden verzonden.

Dead betekent dat alle automatische pogingen voor een probleem waarvoor opnieuw proberen mogelijk was, zijn gebruikt zonder een succesvolle respons te ontvangen.

Bewaartermijn van de geschiedenis

Bezorgingsrecords worden gedurende een beperkte tijd bewaard:

• Geslaagde productiebezorgingen: 30 dagen
• Mislukte productiebezorgingen: 90 dagen
• Dead-productiebezorgingen: 90 dagen
• Testbezorgingen: 30 dagen

Bewaar je eigen integratielogboeken wanneer je een langere auditgeschiedenis nodig hebt. Sla Event ID’s en Delivery ID’s op, maar vermijd het onnodig opslaan van secrets.

Een bezorging opnieuw afspelen

Klik op “Replay” wanneer een voltooide productiebezorging opnieuw moet worden geprobeerd.

Replay is beschikbaar voor productiebezorgingen met de status Success, Failed of Dead. Het is niet beschikbaar zolang een bezorging Pending is en testbezorgingen kunnen niet opnieuw worden afgespeeld.

Een replay:

• Maakt een nieuwe Pending-bezorging aan.
• Maakt een nieuwe Delivery ID aan.
• Behoudt de oorspronkelijke Event ID.
• Behoudt het oorspronkelijke gebeurtenistype en de oorspronkelijke JSON-payload.
• Gebruikt de oorspronkelijke opgeslagen doel-URL en momentopname van aangepaste headers.
• Gebruikt het huidige Signing secret wanneer het nieuwe verzoek wordt voorbereid.

Replay bouwt de payload niet opnieuw op basis van de huidige gegevens van de abonnee. De oorspronkelijke momentopname van de gebeurtenis wordt opnieuw verzonden. Hierdoor blijft de replay controleerbaar en verandert een historische gebeurtenis niet ongemerkt van betekenis.

Er kan slechts één replay van dezelfde bronbezorging tegelijk Pending zijn. Wacht totdat die replay is voltooid voordat je opnieuw een replay aanvraagt.

Zorg ervoor dat het endpoint Active is voordat je een replay uitvoert. Als het endpoint inactief is, kan de wachtrij-replay niet succesvol worden bezorgd.

Omdat een ontvanger de bedrijfsactie mogelijk al heeft voltooid terwijl Maildroppa geen succesrespons heeft ontvangen, kan een replay een dubbel verzoek veroorzaken. Deduplicatie op basis van Event ID beschermt het verbonden systeem tegen het herhalen van de actie.

Een endpoint bewerken

Klik op “Edit” om de URL, gebeurteniskeuze, aangepaste headers of actieve status te wijzigen.

Controleer vóór het opslaan:

1. Bevestig dat de nieuwe URL al beschikbaar is.
2. Laat opgeslagen headerwaarden leeg wanneer ze ongewijzigd moeten blijven.
3. Voer voor elke hernoemde header een nieuwe waarde in.
4. Controleer de gebeurteniskeuze, zodat vereiste meldingen niet per ongeluk worden verwijderd.
5. Sla op en verstuur een nieuwe Test webhook.

Onthoud dat bezorgingen in de wachtrij hun bestaande URL en momentopname van aangepaste headers behouden. Test de nieuwe configuratie voor toekomstige bezorgingen en ga er niet van uit dat deze een oudere bezorging in de wachtrij wijzigt.

Een endpoint deactiveren

Gebruik de On/Off-schakelaar wanneer je een integratie wilt pauzeren zonder de configuratie en geschiedenis te verwijderen.

Wanneer een endpoint wordt uitgeschakeld:

• Worden er geen nieuwe gebeurtenissen meer voor in de wachtrij geplaatst.
• Worden Pending-bezorgingen die nog niet voor verzending zijn geclaimd, gemarkeerd als Failed.
• Is Test uitgeschakeld.
• Blijft het endpoint beschikbaar voor bewerking en latere activering.

Een verzoek dat op het moment van deactivering al wordt verwerkt, kan nog steeds worden voltooid. Controleer de bezorggeschiedenis nadat je het endpoint hebt uitgeschakeld als dit onderscheid belangrijk is voor je integratie.

Gebeurtenissen die zijn gemist terwijl het endpoint inactief was, worden niet aangevuld wanneer je het opnieuw inschakelt.

Een endpoint verwijderen

Klik op “Delete” en bevestig de waarschuwing wanneer het endpoint niet langer mag bestaan.

Door het verwijderen verdwijnt het endpoint van de pagina, worden toekomstige gebeurtenisbezorgingen gestopt en worden Pending-bezorgingen die nog niet voor verzending zijn geclaimd, gemarkeerd als Failed.

Delete is niet bedoeld om tijdelijk te pauzeren. Gebruik de On/Off-schakelaar wanneer je de configuratie of de zichtbare geschiedenis later mogelijk opnieuw nodig hebt.

Noteer vóór het verwijderen alle Event ID’s of Delivery ID’s die je nog nodig hebt voor je integratie-audit.

Problemen oplossen

Het endpoint kan niet worden opgeslagen

Controleer of:

• De URL met https:// begint.
• De URL een openbare hostnaam en poort 443 gebruikt.
• De URL geen variabelen, aanmeldgegevens of fragment bevat.
• Ten minste één gebeurtenis is geselecteerd.
• Elke Custom header een unieke naam en een waarde heeft.
• Gereserveerde Maildroppa- en HTTP-headers niet als aangepaste namen worden gebruikt.

Test is uitgeschakeld

Test is alleen beschikbaar voor een Active endpoint. Schakel het endpoint in of bewerk het en selecteer “Active”. Sla vervolgens op voordat je test.

Test toont geen HTTP-poging

Genereer een Signing secret als de status Missing is. Controleer ook of de hostnaam van de bestemming openbaar is en nog steeds correct wordt opgelost.

Een verzoek kan vóór verzending worden afgewezen wanneer het secret, de URL, aangepaste headers of de veiligheidscontrole van de bestemming ongeldig zijn.

De ontvanger retourneert 401 of 403

Controleer de opgeslagen naam en aanmeldgegevens van de Custom header. Bewerk het endpoint en voer de waarde opnieuw in als deze is gewijzigd.

Controleer ook of de ontvanger zijn eigen API-aanmeldgegeven niet verwart met de Maildroppa-handtekening. Een aangepaste autorisatieheader en X-Maildroppa-Signature dienen verschillende doelen en kunnen onafhankelijk van elkaar worden gecontroleerd.

De ontvanger retourneert een redirect

Maildroppa volgt geen redirects. Vervang de endpoint-URL door de uiteindelijke openbare HTTPS-URL en test opnieuw.

De handtekening komt niet overeen

Controleer of de ontvanger:

• Het huidige Signing secret gebruikt.
• De exacte waarde van X-Maildroppa-Timestamp gebruikt.
• <timestamp>.<raw request body> ondertekent.
• HMAC-SHA256 en hexadecimale uitvoer in kleine letters gebruikt.
• De volledige waarde inclusief v1= vergelijkt.
• De vergelijking uitvoert voordat het parsen van JSON de body wijzigt.

Dezelfde gebeurtenis komt meer dan één keer binnen

Dit kan gebeuren na een netwerkonderbreking, nieuwe poging of handmatige replay. Het is normaal dat webhookbezorgingssystemen minstens één keer bezorgen in plaats van precies één keer.

Gebruik de Event ID als idempotentiesleutel. Retourneer een 2xx-respons wanneer een reeds verwerkte Event ID opnieuw wordt ontvangen en er geen extra actie nodig is.

Een bezorging is Pending

Bekijk “Next retry” in de HTTP-kolom. Een retrybare 408, 429, 5xx of tijdelijke netwerkfout blijft Pending tot de volgende geplande poging.

Klik na het tijdstip van de nieuwe poging op “Refresh” om de nieuwste status te laden.

Een bezorging is Dead

Alle automatische pogingen zijn gebruikt. Los eerst het probleem bij de ontvanger op, zorg dat het endpoint Active is, verstuur een Test webhook en gebruik daarna Replay bij de productiebezorging.

Aanbevolen productiechecklist

Bevestig het volgende voordat je in productie op een endpoint vertrouwt:

1. De ontvanger gebruikt een stabiele openbare HTTPS-URL met een geldig certificaat.
2. Het Signing secret wordt buiten de broncode opgeslagen.
3. De handtekening wordt gecontroleerd tegen de ongewijzigde raw body.
4. Oude timestamps worden afgewezen volgens een gedocumenteerde tolerantie.
5. De ontvanger slaat Event ID’s op en dedupliceert ze.
6. De ontvanger logt Event ID’s en Delivery ID’s voor tracering.
7. Traag werk vindt plaats nadat de gebeurtenis duurzaam is geaccepteerd.
8. Alleen voor geaccepteerde gebeurtenissen wordt een 2xx-respons geretourneerd.
9. Aangepaste aanmeldgegevens worden in headers en niet in de URL opgeslagen.
10. Alleen vereiste gebeurtenistypen zijn geselecteerd.
11. Een Test webhook slaagt en verschijnt correct in de bezorggeschiedenis.
12. Monitoring waarschuwt je wanneer productieleveringen fouten beginnen te retourneren.

Met deze beveiligingen biedt de pagina Webhooks beide kanten van een betrouwbare integratie: veilige bezorging van gebeurtenissen aan je applicatie en een duidelijke operationele geschiedenis binnen Maildroppa.