Hoe u meldingen over de voltooiing van API-bestellingen instelt

Welke gebeurtenissen gelden als voltooiing van een bestelling

Leg eerst vast welke status in de API de daadwerkelijke voltooiing van een bestelling betekent. Bij verschillende leveranciers kan dit een uitgevoerde, geleverde, geannuleerde, afgewezen, geretourneerde of gedeeltelijk uitgevoerde bestelling zijn. Koppel automatisering niet alleen aan het woord 'succes': een bestelling kan meerdere tussenliggende statussen doorlopen en daarna stoppen door een limiet, controle of annulering.

U moet niet alleen een positief resultaat verwerken. Als de dienst een melding stuurt over een fout, annulering, retour of gedeeltelijke uitvoering, moet die ook in het interne systeem worden vastgelegd. Anders blijft de bestelling in het dashboard, de CRM of de bot in afwachting, terwijl verdere uitvoering al niet meer zal plaatsvinden.

Maak een tabel met statuskoppelingen

Geef de API-status niet ongefilterd door aan de interface. De namen en logica van de leverancier kunnen veranderen, en dezelfde interne status omvat soms meerdere externe statussen. Bewaar de oorspronkelijke waarde apart: die is nuttig voor foutanalyse en verificatie met de documentatie.

• pending, created, queued — een nieuwe bestelling of een bestelling die wacht op verwerking.
• processing, in_progress, running — de bestelling wordt uitgevoerd.
• completed, delivered, success — een uitgevoerde bestelling.
• partial, partially_completed — een gedeeltelijk uitgevoerde bestelling.
• cancelled, rejected, failed — een geannuleerde bestelling of een bestelling die met een fout is beëindigd.
• refunded, returned — de bestelling vereist een terugbetaling of correctie.
• Onbekende status — wijzigt de kaart niet automatisch en wordt ter controle doorgegeven.

De bovenstaande namen zijn een voorbeeld van een schema. De definitieve tabel moet worden opgebouwd op basis van de statussen van de specifieke API. Het nadeel van handmatige mapping is dat u deze moet onderhouden na een API-update: een nieuwe status kan de handler eerder bereiken dan dat er een regel voor bestaat.

Kies webhooks, API-polling of beide schema's

Een webhook is een verzoek van de dienst naar uw URL bij een statuswijziging van een bestelling. API-polling werkt omgekeerd: uw systeem vraagt met een interval informatie over de bestelling op. Voor meldingen over voltooiing zijn webhooks meestal handiger, omdat de update binnenkomt zonder voortdurende verzoeken aan de methode voor statuscontrole.

• Webhooks zijn geschikt voor snelle reactie: bijwerken van de kaart, starten van de volgende fase of sturen van een bericht naar de verantwoordelijke.
• Polling is geschikt als de leverancier geen callback-meldingen ondersteunt of de server geen externe verzoeken accepteert.
• Een gecombineerd schema gebruikt webhooks als hoofdkanaal en polling om gemiste of vastgelopen bestellingen op te sporen.

Het nadeel van polling is vertraging en extra belasting van de API. Het nadeel van webhooks is dat u het endpoint moet beveiligen, rekening moet houden met duplicaten en niet mag vertrouwen op de leveringsvolgorde van gebeurtenissen.

Stel een endpoint in voor het ontvangen van gebeurtenissen

Voor meldingen is een openbaar HTTPS-adres nodig dat bereikbaar is vanaf de API-dienst. In de integratie-instellingen geeft u meestal de URL van de handler, het handtekeninggeheim en de lijst met gebeurtenissen op: statuswijziging, voltooiing, annulering, fout of gedeeltelijke uitvoering.

Wijs een aparte route toe alleen voor API-gebeurtenissen. Zo kunt u eenvoudiger logging instellen, toegang beperken, verzoeklimieten instellen en serviceverkeer niet vermengen met websiteformulieren. Gebruik geen adres van de testomgeving voor productiebestellingen: na een update van de omgeving blijft de leverancier gebeurtenissen naar de opgeslagen URL sturen.

Controleer vóór de lancering de verzoekmethode en het formaat van de body volgens de documentatie. Meestal is dit POST met JSON, maar form-data, queryparameters of een eigen serialisatieschema komen ook voor. Een parseerfout moet in het log worden vastgelegd, anders is het moeilijk om een ongeldige payload te onderscheiden van een applicatiefout.

Bewaar de koppeling tussen bestelling en gebeurtenis

Bewaar bij het aanmaken van een bestelling via de API de identificatie die de leverancier heeft teruggegeven. Bewaar daarnaast het interne bestelnummer, het type dienst, de oorspronkelijke status, het tijdstip van de laatste wijziging en het oorspronkelijke API-antwoord in veilige vorm. Koppel een inkomende webhook op basis van het ID van de leverancier, niet op basis van een kanaallink, dienstnaam of klantnaam.

Als de API toestaat een externe identificatie mee te geven bij het aanmaken, voeg dan uw eigen bestelnummer toe in een veld zoals external_id of client_reference. Dat vereenvoudigt zoeken in logs en het analyseren van betwiste situaties. Maar maak het externe nummer niet de enige sleutel: sommige leveranciers sturen het niet in elke melding mee.

Maak geen nieuwe bestelling aan op basis van een onbekend ID uit een webhook. Een onbekende gebeurtenis moet in het log worden bewaard en apart worden gecontroleerd. Automatisch een record aanmaken kan leiden tot onjuiste gegevens of verwerking van een vervalst verzoek.

Gebruik een duidelijke payload-structuur

De exacte veldnamen zijn afhankelijk van de API. Hieronder staat geen contract van een specifieke dienst, maar een voorbeeld van een JSON-gebeurtenis die u kunt gebruiken bij het ontwerpen van de interne handler. Belangrijk zijn de gebeurtenis-ID, het bestel-ID bij de leverancier, de status, het tijdstip van wijziging en gegevens voor diagnostiek.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

Gebruik het aantal uitgevoerde eenheden niet als teken van voltooiing zonder status. Een bestelling kan gedeeltelijk zijn uitgevoerd, en het aantal in de payload kan zijn afgerond, met vertraging zijn bijgewerkt of helemaal niet zijn meegestuurd. Het nadeel van het opslaan van de volledige gebeurtenis-body is dat er persoonsgegevens of servicevelden in kunnen staan, dus zulke records moeten worden gemaskeerd en een beperkte bewaartermijn krijgen.

Controleer de handtekening op basis van de oorspronkelijke verzoekbody

Een openbare handler-URL kan een verzoek ontvangen dat niet van de API-dienst afkomstig is. Als de leverancier een handtekening, geheim of token meestuurt, controleer deze dan vóór het wijzigen van de bestelling. Een veelvoorkomend schema is HMAC-SHA256: de leverancier berekent een handtekening uit de bytes van de verzoekbody en een gedeeld geheim, en stuurt het resultaat vervolgens mee in een HTTP-header.

Het berekeningsprincipe ziet er zo uit: neem de oorspronkelijke verzoekbody, bijvoorbeeld de JSON-bytes zonder wijzigingen, en het integratiegeheim. Bereken vervolgens HMAC-SHA256. Als het resultaat in hexadecimale vorm overeenkomt met de waarde in de header, is de body na ondertekening niet gewijzigd en is het verzoek waarschijnlijk verzonden door een partij die het geheim kent.

Voorwaardelijk voorbeeld: HMAC_SHA256(geheim, raw_body) = handtekening uit de header X-Signature. De naam van de header, het algoritme en het formaat van het resultaat moeten alleen uit de API-documentatie worden gehaald. Sommige diensten voegen een tijdstempel of gebeurtenis-ID toe aan de string voor de handtekening. In dat geval mag u niet alleen de JSON-body controleren.

Wijzig JSON niet vóór verificatie van de handtekening

De handtekening wordt gecontroleerd op basis van de oorspronkelijke bytes van het verzoek, niet op basis van het JSON-object dat de applicatie al heeft geparseerd en opnieuw heeft samengesteld. Bij herserialisatie kunnen de volgorde van velden, spaties, tekenescaping, regeleinden of codering veranderen. Voor een mens blijft de JSON hetzelfde, maar de set bytes verandert en de HMAC komt niet meer overeen.

Om dit te voorkomen, haalt u eerst de raw body op als bytes of buffer, bewaart u deze in het geheugen, berekent u de handtekening en parseert u de JSON pas na een succesvolle controle. Pas geen trim, coderingsconversie, sleutelsortering of formattering toe op de body. Controleer in de middleware van het framework of JSON niet automatisch wordt geparseerd voordat u toegang hebt tot de oorspronkelijke body.

Het nadeel van dit schema is dat de handler afhankelijk wordt van de volgorde van middleware. Bij een onjuiste configuratie ziet de applicatie alleen het getransformeerde object en worden legitieme meldingen afgewezen.

Voorbeeld van een handler met HMAC-verificatie

Hieronder staat een voorwaardelijk voorbeeld in Python. Het toont de volgorde van handelingen, niet een kant-en-klare integratie: headers, algoritme, handtekeningformaat en payload-velden moeten worden vervangen door de waarden uit de documentatie van de leverancier.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

Gebruik voor de vergelijking een functie die niet stopt bij het eerste niet-overeenkomende teken. Dit verkleint het risico op het lekken van gegevens over de handtekening via de responstijd. Geef het geheim niet door aan clientcode, voeg het niet toe aan de URL en schrijf het niet volledig in logs.

Maak de verwerking van gebeurtenissen idempotent

De leverancier kan dezelfde gebeurtenis meerdere keren leveren. De oorzaken zijn gewoon: uw server antwoordde langzaam, de verbinding werd verbroken na het opslaan van gegevens, het endpoint gaf tijdelijk een fout terug of de dienst startte een herhaalde levering volgens zijn eigen regels. Een herhaling betekent niet dat de API een nieuwe bestelling heeft aangemaakt.

Idempotentie betekent dat dezelfde gebeurtenis het resultaat slechts één keer wijzigt. Als u deze regel niet toepast, stuurt een duplicaat opnieuw een bericht naar de klant, maakt meerdere taken voor de manager aan, kent een compensatie toe of start een herhaalde operatie.

Het beste is om event_id uit de payload te gebruiken. Bewaar dit in een aparte tabel of een log van verwerkte gebeurtenissen met een unieke beperking. Als er geen apart ID is, vormt u een sleutel uit stabiele velden: bestel-ID van de leverancier, type gebeurtenis, status en tijdstip van wijziging. Deze variant is slechter: bij onnauwkeurige tijdstempels kunnen verschillende gebeurtenissen er hetzelfde uitzien.

Bewaar gebeurtenis en status in één operatie

De controle 'is de gebeurtenis al verwerkt' en het vastleggen van het resultaat moeten atomair worden uitgevoerd. Anders zien twee identieke verzoeken die tegelijk binnenkomen beide dat er geen record is en starten de actie twee keer. Een praktische variant is een unieke index op event_id en een databasetransactie.

Een voorwaardelijk vervolg van de handler ziet er zo uit:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

Het nadeel van een succesvol antwoordcode voor een onbekende bestelling is dat de leverancier de levering mogelijk niet herhaalt. Daarom moeten onbekende gebeurtenissen apart worden gemonitord en snel worden geanalyseerd. Als de API-documentatie een andere antwoordcode aanbeveelt voor zulke gevallen, volg die dan.

Houd rekening met een verstoorde volgorde van gebeurtenissen

Webhooks komen niet altijd strikt in de volgorde van statuswijziging binnen. Eerst kan een gebeurtenis over voltooiing binnenkomen en daarna een vertraagde melding over de status 'in uitvoering'. Als u simpelweg de laatst ontvangen waarde opslaat, wordt een uitgevoerde bestelling weer actief.

Stel toegestane overgangen in. Een tussenstatus mag bijvoorbeeld een eindstatus niet overschrijven, en een geannuleerde bestelling wordt niet naar uitgevoerd gezet zonder aparte controle. Als de API correctie van de eindstatus toestaat, bewaar dan de reden, de oorspronkelijke waarde en de bron van de wijziging.

Als de payload het tijdstip van wijziging van de bestelling bevat, vergelijk dan juist dat en niet het tijdstip waarop de webhook is ontvangen. Als de API zo'n markering niet meestuurt, gebruik dan prioriteiten van statussen en verificatie via de methode om de bestelling op te halen. Het nadeel van prioriteiten is dat ze de werkelijke volgorde niet vervangen, vooral niet als de leverancier een retour uit een eindstatus toestaat.

Bevestig levering snel en plaats acties in een wachtrij

Voer geen langdurige bewerkingen uit voordat u de leverancier antwoordt. Verificatie van de handtekening, het zoeken van de bestelling, het vastleggen van de gebeurtenis en het bijwerken van de status kunnen meestal snel worden afgerond. Het versturen van een bericht, synchronisatie met de CRM, het genereren van een rapport of verzoeken aan externe systemen kunt u beter in een taakwachtrij plaatsen.

De werkvolgorde is als volgt: controleer de handtekening, sla de gebeurtenis en statuswijziging atomair op, geef een succesvol antwoord terug en voer daarna secundaire acties uit. Als u antwoordt vóór het opslaan, gaan gegevens verloren bij een storing. Als u antwoordt na een langdurige verzending van een melding, kan de leverancier de levering als mislukt beschouwen en een duplicaat sturen.

Het nadeel van een wachtrij is dat er een apart component bijkomt dat u moet bewaken: taakfouten, vertragingen en herhaalde uitvoeringen. Maar een storing in de melding aan de manager blokkeert dan niet de ontvangst van bestelstatussen.

Stel meldingen in voor het team en de klant

Na een statuswijziging hoeft u niet iedereen op dezelfde manier te melden. Voor een manager zijn annuleringen, fouten, gedeeltelijke uitvoering en bestellingen die lang niet veranderen meestal belangrijk. Voor de klant is vaak een begrijpelijke uitkomst voldoende: de bestelling is uitgevoerd, geannuleerd of vereist verduidelijking.

• Uitgevoerde bestelling — een update in het klantportaal of een kort bericht aan de klant.
• Uitvoeringsfout — een melding aan de verantwoordelijke met de reden die de API heeft doorgegeven.
• Gedeeltelijke uitvoering — een taak voor controle van correctie, terugbetaling of een volgende actie.
• Onbekende status — een vermelding in het log en een bericht aan de technisch specialist.
• Onbekend bestel-ID — een aparte controle van de koppeling tussen uw systeem en de leverancier.

Stuur geen bericht bij elke technische overgang. De feed verandert snel in ruis, en een belangrijk probleem blijft onopgemerkt. Een interne melding moet het bestelnummer, de dienst, de huidige status, het externe ID en een link naar de kaart bevatten.

Houd een log bij en controleer niet-voltooide bestellingen

Logs zijn nodig om te begrijpen of de dienst een gebeurtenis heeft gestuurd, welke body is ontvangen, waarom de handtekening niet is geslaagd en in welke fase de verwerking is gestopt. Bewaar het tijdstip van ontvangst, de gebeurtenis-ID, het bestel-ID, het type gebeurtenis, het resultaat van de handtekeningcontrole, de interne status en de antwoordcode. Maskeer geheimen, tokens en persoonsgegevens.

Houd apart toezicht op leveringsfouten, ongeldige handtekeningen, onbekende bestellingen, niet-ondersteunde statussen, duplicaten en gebeurtenissen die niet kunnen worden toegepast door de volgorde van statussen. Een toename van zulke records kan wijzen op een wijziging in het API-schema, een verlopen geheim, een fout in de route of een fout in de logica van de handler.

Controleer periodiek bestellingen in tussenstatussen via de methode om gegevens uit de API op te halen. Deze controle vervangt webhooks niet, maar helpt een gemiste gebeurtenis, een wachtrijstoring of een geval waarin de externe status is gewijzigd zonder correcte melding op te sporen.