Naar hoofdinhoud gaan
De integratie Webhooks is bedoeld voor developers. Ze stuurt een JSON-event naar een HTTPS-adres dat je zelf kiest wanneer er iets gebeurt in Foliant. Zo kan je eigen systeem reageren, bijvoorbeeld door elke factuur-pdf te archiveren of een afgeronde export op te halen. Webhooks is in bèta. Zie je het niet in Instellingen › Integraties? Dan is het nog niet beschikbaar voor je winkel. Neem contact op met support om toegang te vragen.

Events

Webhooks koppelen

  1. Ga in Foliant naar Instellingen › Integraties.
  2. Klik bij Webhooks op Koppelen.
  3. Vul de instellingen in:
  4. Klik op Koppelen.
Je kunt de URL, het secret en de events later wijzigen via Instellingen op de pagina van de integratie.

Wat elk verzoek bevat

Foliant stuurt een POST-verzoek met een JSON-body:

Data van document.generated

  • template: de uuid en name van de template.
  • document_type: invoice, credit_note, quote, of leeg voor andere documenten.
  • order: de id, name en type (bestellingen of conceptbestellingen).
  • refund_id en fulfillment_id, als het document bij een terugbetaling of een zending hoort.
  • document_number en issued_at, voor genummerde documenten.
  • source: hoe het document is gemaakt, zoals download, admin_download, export of email.
  • export: de ID van de export, als het document deel is van een export.
  • generated_at.

Data van export.completed

  • export: de uuid, order_type, template_uuids, het aantal orders, orders_skipped (verwijderd nadat ze waren gekozen) en documents, requested_by (merchant of customer) en completed_at.
  • download_url: een link om de export te downloaden, en download_url_expires_at, het moment waarop die link niet meer werkt.
  • download_expires_at: het moment waarop de export zelf verloopt.
Events bevatten ID’s en aantallen, geen e-mailadressen van klanten.

Headers

De handtekening controleren

De handtekening is een hex HMAC-SHA256 van de timestamp, een punt en de ruwe request-body (<timestamp>.<body>), met je signing secret als sleutel. Bereken hem zelf en vergelijk hem met de waarde na sha256= in X-Foliant-Signature. Gebruik de ruwe body precies zoals je die hebt ontvangen.

Responses en nieuwe pogingen

  • Elke 2xx-response telt als afgeleverd.
  • Geeft je endpoint een 5xx-fout, 408 of 429, of antwoordt het niet binnen 10 seconden? Dan probeert Foliant het later opnieuw. Het wacht elke keer langer, tot maximaal 5 pogingen.
  • Andere 4xx-responses zijn definitief: Foliant probeert die niet opnieuw.
  • Elk event wordt één keer per document of export afgeleverd. Na een geslaagde levering wordt het nooit nog eens verstuurd.
Elke levering staat in Activiteit op de pagina van de integratie. Daar kun je een mislukte levering Opnieuw proberen. Zie Activiteit van integraties.

Gerelateerde artikelen