Batch hooks: documenten in bulk ophalen

Standaard stuurt de PSB voor elk ontvangen document direct een webhook-notificatie. Bij grote volumes kan het efficienter zijn om documenten periodiek in bulk te verwerken. Met een batch hook verzamelt de PSB alle events gedurende een instelbare periode en maakt er een ZIP-archief van.

Hoe werkt een batch hook?

Een batch hook luistert op een topic (bijvoorbeeld InvoiceReceived) en verzamelt alle events die in een bepaalde periode binnenkomen. Na afloop van de periode maakt de PSB een ZIP-bestand met alle documenten die bij die events horen. De PSB publiceert vervolgens een nieuw topic ({Topic}Batched) zodat je het archief kunt downloaden.

De flow is als volgt:

De PSB ontvangt documenten en registreert events
De batch hook verzamelt events tot de periode is verstreken of het maximum aantal is bereikt
De PSB maakt een ZIP-archief van alle verzamelde documenten
Een {Topic}Batched-event wordt gepubliceerd (bijvoorbeeld InvoiceReceivedBatched)
Je webhook ontvangt het batched-event en downloadt het ZIP-archief

Een batch hook aanmaken

Registreer een hook via de API met een batch://zip-action:

{
  "action": "batch://zip?period=00:15:00&maxBatchSize=100",
  "topics": ["InvoiceReceived"]
}

Parameters

Parameter

Standaard

Beschrijving

period

00:15:00 (15 minuten)

De verzamelperiode in het formaat uu:mm:ss. Na deze periode wordt de batch afgesloten en het ZIP-archief aangemaakt.

maxBatchSize

100

Het maximale aantal events per batch. Als dit aantal wordt bereikt voor het einde van de periode, wordt de batch direct afgesloten.

Tip: Kies de period en maxBatchSize op basis van je documentvolume. Bij lage volumes kun je een langere periode instellen (bijvoorbeeld een uur). Bij hoge volumes is een kortere periode met een hogere maxBatchSize handiger.

Publish topic

Na het afsluiten van een batch publiceert de PSB een nieuw event op het topic {Topic}Batched. De naamgeving volgt een vast patroon:

Bron-topic

Batched-topic

InvoiceReceived

InvoiceReceivedBatched

OrderReceived

OrderReceivedBatched

Stel een reguliere webhook in op het batched-topic om het ZIP-archief op te halen:

{
  "action": "https://jouw-endpoint.nl/batches",
  "topics": ["InvoiceReceivedBatched"],
  "secret": "jouw-geheime-sleutel"
}

ZIP-archief

Het ZIP-bestand bevat alle documenten die in de batch zijn verzameld, elk als apart XML-bestand. De bestandsnamen zijn gebaseerd op het documentId. Het archief kan worden gedownload via de URL die in het batched-event wordt meegegeven.

Combinatie met reguliere hooks

Je kunt batch hooks combineren met reguliere webhooks. Gebruik bijvoorbeeld een reguliere webhook voor directe verwerking van urgente documenten en een batch hook voor periodieke bulk-import in je ERP-systeem. Zorg er wel voor dat je geen documenten dubbel verwerkt als je beide hooks op hetzelfde topic hebt staan.

Let op: Batch hooks gebruiken dezelfde retry-logica als reguliere webhooks. Als het batched-event niet succesvol wordt afgeleverd, probeert de PSB het maximaal 5 dagen opnieuw.

Veelgestelde vragen

Op welk topic moet ik luisteren om het ZIP-archief van een batch hook op te halen?

Na afloop van de verzamelperiode publiceert de PSB een event op {Topic}Batched, bijvoorbeeld InvoiceReceivedBatched bij bron-topic InvoiceReceived. Registreer een gewone webhook op dat batched-topic om de download-URL te ontvangen en het ZIP-bestand op te halen.

Hoe werken period en maxBatchSize samen?

period (standaard 15 minuten) bepaalt hoelang events worden verzameld voordat de batch wordt afgesloten; maxBatchSize (standaard 100) sluit de batch eerder af als die limiet eerder wordt bereikt. Stem beide af op je volume: langere perioden bij weinig documenten, kortere perioden of hogere limieten bij piekverkeer.

Kan ik een batch hook en een directe webhook op hetzelfde topic combineren?

Ja, maar let op dubbele verwerking: als beide op hetzelfde bron-topic staan, kan hetzelfde document twee keer binnenkomen. Gebruik alleen beide als je dat expliciet afvangt, bijvoorbeeld direct voor urgente zaken en batch voor bulk-import.

Bekijk de volledige API-specificatie op psb.econnect.eu voor alle configuratiemogelijkheden.

Bekijk de API-documentatie

Gerelateerd