Skip to main content
HomeBlogGidsenWat moet een tracking-webhookendpoint retourneren? Statuscodes, time-outs en nieuwe pogingen?

Wat moet een tracking-webhookendpoint retourneren? Statuscodes, time-outs en nieuwe pogingen?

17TRACK

Een tracking-webhook-endpoint moet een snelle, bewuste 2xx-respons retourneren nadat het de gebeurtenis voor verwerking heeft geaccepteerd. In de meeste integraties is het veiligste patroon: het verzoek authenticeren, de payload valideren, de gebeurtenis opslaan of in een wachtrij plaatsen en deze bevestigen met 200 OK of 202 Accepted. Gebruik 4xx-responsen voor verzoeken die de afzender niet opnieuw moet proberen, en 5xx-responsen wanneer een tijdelijk probleem aan de serverzijde ervoor zorgde dat acceptatie niet mogelijk was. Het exacte time-out- en retrygedrag hangt nog steeds af van het contract van de webhookprovider. Uw implementatie moet daarom gebaseerd zijn op gedocumenteerd gedrag van de afzender en niet op aannames.

Welke statuscodes en time-outs moet een tracking-webhook-endpoint retourneren

Voor een webhook voor tracking of verzendstatus is dit onderscheid belangrijk, omdat bezorgingsgebeurtenissen meer dan één keer kunnen aankomen, in een andere volgorde kunnen aankomen of na een netwerkfout opnieuw kunnen worden afgespeeld. Het is niet noodzakelijk de taak van het endpoint om elke bedrijfsbewerking te voltooien voordat het antwoordt. De eerste taak is een betrouwbare beslissing nemen over de vraag of de gebeurtenis is geaccepteerd.

Het responsecontract in de praktijk

Een webhook-respons heeft twee doelgroepen: het verzendende systeem en uw eigen applicatie. De afzender heeft een duidelijk HTTP-resultaat nodig om te kunnen beslissen of de levering als geslaagd moet worden gemarkeerd, opnieuw moet worden geprobeerd of moet worden gestopt. Uw applicatie heeft voldoende tijd nodig om de gebeurtenis te verifiëren en duurzaam vast te leggen. Deze doelen zijn eenvoudiger te bereiken wanneer het endpoint een klein synchroon pad en een afzonderlijk asynchroon verwerkingspad heeft.

  1. Ontvang het HTTP-verzoek via HTTPS.
  2. Controleer de handtekening, authenticatiegegevens, tijdstempel of andere vereiste controles voor de integriteit van het verzoek.
  3. Parseer en valideer de payload zonder trage downstream-bewerkingen uit te voeren.
  4. Schrijf de gebeurtenis, of een deduplicatierecord en gebeurtenisreferentie, naar duurzame opslag of een betrouwbare wachtrij.
  5. Retourneer een bewuste 2xx-respons.
  6. Verwerk de trackingupdate, klantmelding, voorraadwijziging of andere bedrijfsactie asynchroon.

Een respons mag geen acceptatie claimen als de gebeurtenis alleen in het procesgeheugen bestaat. Als de applicatie direct na het retourneren van succes crasht, kan een gebeurtenis die nooit is opgeslagen verloren gaan terwijl de afzender denkt dat de levering is geslaagd. Het moment waarop u 2xx retourneert, moet daarom overeenkomen met uw werkelijke garantie voor duurzaamheid.

Welke statuscode moet een webhook retourneren?

ResponsBetekenis voor de afzenderTypisch webhookgebruik
200 OKHet verzoek is geaccepteerd en succesvol verwerkt.Een praktische standaard na validatie en duurzame acceptatie.
202 AcceptedHet verzoek is geaccepteerd voor verwerking, maar de werkzaamheden kunnen doorgaan.Nuttig wanneer de gebeurtenis veilig in een wachtrij is geplaatst, maar de bedrijfsverwerking asynchroon verloopt.
204 No ContentHet verzoek is geslaagd en er is geen response body nodig.Geschikt wanneer de provider een lege succesrespons accepteert.
400–499Het verzoek is ongeldig, niet geautoriseerd of in de huidige vorm niet acceptabel.Ongeldige payload, mislukte authenticatie, ongeldige handtekening of permanent afgewezen gebeurtenis.
429 Too Many RequestsDe ontvanger past snelheidsbeperking toe.Gebruik dit alleen wanneer het retrygedrag van de afzender en uw beleid voor snelheidsbeperking op elkaar aansluiten.
500–599De ontvanger kon het verzoek niet accepteren vanwege een probleem aan de serverzijde of een tijdelijk probleem.Database-uitval, wachtrijfout, fout bij een afhankelijkheid of onverwachte applicatiefout.

200 OK is vaak de minst verrassende keuze, omdat deze algemeen wordt begrepen als succesvolle ontvangst. 202 Accepted is semantisch ook nuttig wanneer het endpoint de gebeurtenis voor latere verwerking heeft geaccepteerd. Geen van beide codes is automatisch correct: de documentatie van de afzender kan bepalen welke 2xx-responsen als succesvol gelden, en sommige providers verwachten een specifieke body of contenttype.

Retourneer geen 2xx-respons alleen omdat het HTTP-verzoek uw server heeft bereikt. Als de handtekeningverificatie mislukt of de payload niet veilig kan worden geïnterpreteerd, is een 4xx-respons meestal waarheidsgetrouwer. Retourneer daarentegen geen 4xx voor een tijdelijke database-uitval als de gebeurtenis later wel kan slagen. Een 5xx-respons geeft een afzender die retries ondersteunt de kans om de gebeurtenis opnieuw te leveren, hoewel de provider zijn eigen beleid kan toepassen.

Hoe moeten time-outs worden afgehandeld?

De waarden voor webhook-time-outs zijn provider-specifiek. Er bestaat geen universele HTTP-time-out die elk trackingplatform gebruikt, en een afzender kan stoppen met wachten voordat uw applicatie een trage bewerking heeft voltooid. Beschouw de gedocumenteerde time-out van de afzender als een maximale grens, niet als een doel. Uw endpoint moet normaal gesproken ruim vóór die grens antwoorden.

De meest voorkomende ontwerpfout is al het downstream-werk uitvoeren voordat de webhook wordt bevestigd. Een handler kan achtereenvolgens een database, een orderbeheersysteem, een meldingsservice en een analysepipeline aanroepen. Eén trage afhankelijkheid kan ervoor zorgen dat de afzender een time-out ziet, ook al voltooit uw applicatie het werk uiteindelijk. De afzender kan dan opnieuw proberen, waardoor dubbele verwerking of conflicterende updates ontstaan.

Beperk het synchrone pad tot het werk dat nodig is om een veilige acceptatiebeslissing te nemen. Dit omvat doorgaans authenticatie van het verzoek, basisvalidatie van het schema, duurzame opslag van de gebeurtenis en publicatie naar een wachtrij. Plaats kostbare verrijking, opzoekingen bij vervoerders, klantcommunicatie en API-aanroepen van derden achter een worker. Monitor de tijd die afzonderlijk wordt besteed aan het ontvangen, valideren, opslaan en bevestigen van de gebeurtenis, en de tijd die wordt besteed aan de verwerking ervan.

Een time-out is niet hetzelfde als een mislukte bedrijfsbewerking. Vanuit het perspectief van de afzender betekent een time-out meestal dat deze geen bruikbare succesrespons heeft ontvangen. Uw service kan de gebeurtenis succesvol hebben opgeslagen vlak voordat de verbinding werd gesloten. Daarom zijn idempotentie en deduplicatie vereist, zelfs wanneer het endpoint betrouwbaar lijkt.

Wat veroorzaakt retries?

Een webhook-afzender kan opnieuw proberen na een verbindingsfout, een time-out of een respons die volgens het contract als mislukt wordt geclassificeerd. Het exacte schema, het maximale aantal pogingen, het back-off-algoritme en het leveringsvenster verschillen per provider. Beloof geen vast aantal retries tenzij dit in de documentatie van de provider staat.

De ontvanger moet ervan uitgaan dat retries kunnen plaatsvinden en het systeem daar bewust op ontwerpen:

  • Gebruik een gebeurtenis-ID wanneer die beschikbaar is. Sla deze op met een unieke constraint of een gelijkwaardige deduplicatiesleutel.
  • Maak de verwerking idempotent. Het tweemaal toepassen van dezelfde update van de bezorgstatus mag niet leiden tot twee klantberichten, twee terugbetalingen of het onjuist vooruitzetten van een bestelling.
  • Bewaar de oorspronkelijke payload of een bruikbaar auditrecord. Dit ondersteunt opnieuw afspelen, onderzoek en afstemming.
  • Scheid acceptatie van verwerking. Een worker kan interne fouten opnieuw proberen zonder dat de afzender de volledige HTTP-uitwisseling hoeft te herhalen.
  • Registreer responscodes en latentie. Een stijging van 5xx-responsen, time-outs of dubbele gebeurtenis-ID's kan een storing aan het licht brengen voordat gebruikers ontbrekende trackingupdates melden.

Een dubbele gebeurtenis moet doorgaans een succesvolle respons krijgen als de oorspronkelijke gebeurtenis al duurzaam was geaccepteerd. Een fout retourneren voor elke duplicaat kan onnodige retries veroorzaken. Het endpoint kan vastleggen dat de gebeurtenis eerder is gezien, de herhaalde bedrijfsactie overslaan en dezelfde succesklasse retourneren die voor een nieuw geaccepteerde gebeurtenis wordt gebruikt.

Wanneer moet u 4xx, 429 of 5xx retourneren?

Retourneer 4xx wanneer het opnieuw proberen van hetzelfde verzoek het probleem waarschijnlijk niet oplost. Voorbeelden zijn een ongeldige handtekening, ontbrekende vereiste authenticatie, een niet-ondersteunde payloadvorm of een verzoek dat een permanente validatieregel schendt. Controleer voordat u 4xx kiest of de afzender die status als permanente fout behandelt. Sommige platformen hebben eigen regels voor mislukte leveringen.

Gebruik 429 zorgvuldig. HTTP definieert 429 voor snelheidsbeperking en de header Retry-After kan aangeven wanneer een nieuwe poging passend kan zijn. Niet elke webhook-afzender interpreteert 429 echter op dezelfde manier. Als uw wachtrij vol is of uw service overbelast is, controleer dan of de provider veilig opnieuw zal proberen en of zijn retrieschema de overbelasting niet zal verergeren. Een begrensde intakewachtrij en een plan voor backpressure zijn doorgaans beter dan verzoeken onvoorspelbaar te laten mislukken.

Retourneer 5xx wanneer de ontvanger de gebeurtenis door een tijdelijk probleem niet veilig kan accepteren. Dit omvat een niet-beschikbare database, een mislukte schrijfactie naar een duurzame wachtrij of een interne fout die validatie of opslag verhinderde. 200 retourneren terwijl de gebeurtenis stilzwijgend wordt verwijderd, maakt herstel moeilijker omdat de afzender geen reden heeft om het opnieuw te proberen.

Vermijd het gebruik van redirects zoals 301, 302 of 307 voor webhookleveringen. De afhandeling van redirects verschilt per client en het omleiden van een ondertekend verzoek kan onduidelijkheid veroorzaken over de bestemming, methode en body. Configureer de provider in plaats daarvan met het definitieve HTTPS-endpoint.

Een betrouwbaar responsebeleid voor trackinggebeurtenissen

Voor de meeste tracking-webhookintegraties is het volgende beleid een verstandig uitgangspunt:

  1. Retourneer 200 of 202 nadat de gebeurtenis de authenticatie heeft doorstaan en duurzaam is opgeslagen of op een betrouwbare wachtrij is geplaatst.
  2. Retourneer een 4xx-respons voor een ongeldige handtekening, ongeldige authenticatie of permanent onbruikbare payload, volgens de gedocumenteerde regels van de provider.
  3. Retourneer 5xx wanneer een tijdelijke fout duurzame acceptatie verhindert.
  4. Retourneer een succesvolle respons voor een veilig herkende duplicaat, terwijl dubbele bedrijfseffecten worden voorkomen.
  5. Houd de handler snel en meet de latentie van de bevestiging.
  6. Test scenario's met time-outs, retries, duplicaten, gebeurtenissen in de verkeerde volgorde, ongeldige payloads en providerstoringen vóór de productielancering.

Als u een tracking-API integreert, begin dan met de webhookdocumentatie van de provider en bevestig de geaccepteerde succescodes, methode voor het ondertekenen van verzoeken, time-out, retrytriggers, payloadschema en gebeurtenis-ID. Voor 17TRACK-integraties is de officiële documentatie van de Tracking API de juiste plaats om het providerspecifieke contract te controleren, in plaats van dit af te leiden uit algemene HTTP-praktijken.

Implementatiechecklist

  • Het endpoint is bereikbaar via HTTPS en heeft een stabiele productie-URL.
  • Authenticatie en handtekeningverificatie vinden plaats vóór de bedrijfsverwerking.
  • Het onbewerkte verzoek of een verifieerbare representatie wordt bewaard wanneer dit nodig is voor handtekeningcontroles en probleemoplossing.
  • De gebeurtenis wordt opgeslagen voordat de succesrespons wordt verzonden.
  • Dubbele leveringen zijn veilig en herhalen geen onomkeerbare acties.
  • Workers kunnen interne verwerking onafhankelijk van de HTTP-retrycyclus van de afzender opnieuw proberen.
  • Logs bevatten gebeurtenis-ID, leveringstijd, responscode, verwerkingsstatus en correlatie-ID zonder geheimen bloot te leggen.
  • Meldingen maken onderscheid tussen endpoint-time-outs, 4xx-validatiefouten, 5xx-storingen, wachtrijvertragingen en dubbele leveringen.
  • Het gedocumenteerde gedrag van de provider is getest met echte of sandboxgebeurtenissen.

Veelgestelde vragen

Is 200 OK beter dan 202 Accepted voor een webhook?

Geen van beide is universeel beter. Gebruik 200 OK wanneer het verzoek is geaccepteerd en uw integratie de respons als algemeen succes behandelt. Gebruik 202 Accepted wanneer de gebeurtenis is geaccepteerd voor asynchrone verwerking. Controleer of de afzender de gekozen 2xx-respons als succesvol classificeert.

Moet een webhook-endpoint wachten totdat de trackingupdate volledig is verwerkt?

Meestal niet. Het moet alleen wachten totdat de gebeurtenis is geauthenticeerd, gevalideerd en duurzaam geaccepteerd. Langdurige werkzaamheden moeten normaal gesproken na de bevestiging plaatsvinden, zodat een trage afhankelijkheid geen vermijdbare time-out en retry veroorzaakt.

Wat moet er gebeuren wanneer dezelfde trackinggebeurtenis tweemaal aankomt?

Herken deze met de gebeurtenis-ID van de provider of een zorgvuldig ontworpen gelijkwaardige sleutel, sla dubbele neveneffecten over en retourneer een succesrespons als de gebeurtenis al was geaccepteerd. Zo worden retries veilig zonder nieuwe verwerkingsfouten te verbergen.

Moet een ongeldige handtekening 400 of 401 retourneren?

De keuze hangt af van uw authenticatiemodel en de gedocumenteerde verwachtingen van de provider. Beide kunnen afwijzing communiceren, maar consistentie is belangrijker dan één universele keuze. Bevestig geen gebeurtenis waarvan u de authenticiteit niet kunt verifiëren.

Veroorzaakt een 5xx-respons altijd een retry?

Nee. Veel webhooksystemen proberen opnieuw bij time-outs en serverfouten, maar retrytriggers en schema's zijn providerspecifiek. Behandel retries als gedocumenteerd integratiegedrag en verifieer dit in een testomgeving.

Bronnen