Webhooks in CustomerGate 365

Er gaat niets weg zonder abonnement

Webhooks staan uit tot iemand in de Business Central-client een abonnement aanmaakt. Er is geen webservice die een abonnement kan aanmaken of lezen: een adres dat Business Central gaat bellen, en het geheim waarmee dat ondertekend wordt, horen niet iets te zijn wat een website voor zichzelf kan instellen.

Hoe de ontvangende kant een handtekening controleert, met voorbeeldwaarden om het zonder Business Central na te rekenen, staat in de naslag voor websitebouwers. Deze pagina blijft bij de twee schermen.

De gebeurtenissen

Eén abonnement per gebeurtenis; hetzelfde adres mag op meerdere regels staan.

Een baliebezoek meldt Aanvraag omgezet en geen Order aangemaakt: elke gebeurtenis heeft precies één bron, zodat een ontvanger nooit twee namen voor één feit krijgt. Een aanvraag die als spam is gemarkeerd, meldt niets. En de opruimtaak, die oude aanvragen op afgewezen zet terwijl ze de persoonsgegevens wist, meldt evenmin iets: anders regende het elke nacht berichten over aanvragen van een jaar geleden.

Een abonnement instellen

1. Sta de app uitgaande aanroepen toe: kies op de pagina Extensiebeheer CustomerGate 365, dan Configureren, en zet HttpClient-aanvragen toestaan aan. Zonder dat wordt er netjes in de wachtrij geschreven en vertrekt er niets.
2. Maak op Webhookabonnementen een regel met een code, het https-adres en de gebeurtenis.
3. Kies Geheim aanmaken en zet het geheim meteen in de website. Het wordt één keer getoond en is daarna nergens meer op te vragen, ook niet in een export of een databasekopie.
4. Kies Aanzetten. Zonder adres en zonder geheim kan een abonnement niet aan.
5. Kies Proefgebeurtenis versturen. Die gaat er meteen uit en toont welke statuscode eruit terugkwam.
6. Zet de bezorgtaak op Gereed. Net als de mailtaak en de opruimtaak wordt hij in de wachtstand aangelegd; de knop Bezorgtaak opent hem.
7. Controleer op Webhookbezorgingen dat de proefgebeurtenis op Bezorgd staat.

De abonnementenlijst waarschuwt bovenaan als uitgaande HTTP niet toegestaan is of als de bezorgtaak niet op Gereed staat. Dat zijn de twee storingen waarbij alles er goed uitziet en er toch niets vertrekt, en waar dus niemand naar gaat zoeken. Een nieuw geheim maakt het oude op slag ongeldig: tot de website het nieuwe heeft, wijst die elke bezorging af.

De abonnementenlijst

Code, Omschrijving

De korte naam en in één regel wie hier gebeld wordt en waarom. De ontvanger ziet de code terug in de kop X-VOA-Subscription, zodat één eindpunt meerdere abonnementen kan bedienen.

Eindpunt-URL

Het adres dat met POST gebeld wordt. Het moet met https beginnen en meteen antwoorden: een omleiding wordt niet gevolgd met de handtekeningkoppen erbij.

Aan

Of dit abonnement bezorgd wordt. Uitzetten parkeert wat er nog voor klaarstond; dat wordt later niet alsnog verstuurd.

Geheim

Aanwezig of Ontbreekt. Het geheim zelf is nergens te lezen. Geheim verwijderen haalt het weg en zet het abonnement uit.

Mislukkingen op rij, Uitgezet na mislukkingen

Eén gelukte bezorging zet de teller terug op nul. Mislukkingen terugzetten doet dat met de hand, zonder verder iets te wijzigen.

Laatste poging op, Laatste statuscode, Laatste fout

Wat er bij de laatste poging gebeurde. Statuscode nul betekent dat het adres helemaal niet bereikbaar was.

Webhookbezorgingen

Bezorgingen is het logboek: wat er verstuurd is, wat het eindpunt antwoordde en wat er nog wacht. Er valt niets te wijzigen en niets te wissen.

Stand

Bezorgd, Wacht, of Gestrand na vijf pogingen. Gestrand betekent dat de pogingen op zijn en dat de bezorgtaak deze rij uit zichzelf niet meer oppakt.

Gebeurd op, Bezorgd op

Wanneer de gebeurtenis in Business Central plaatsvond, en wanneer het eindpunt de bezorging aannam. Dat is niet hetzelfde moment.

Pogingen, Laatste statuscode, Laatste fout, Volgende poging op

Hoe vaak het geprobeerd is, wat eruit terugkwam (de statuscode en het begin van het antwoord) en wanneer de taak het weer mag proberen.

Documentsoort, Documentnr., Klantnr.

Waar de gebeurtenis over gaat, in de vaste waarden van het webservicecontract.

Payload tonen

Toont de exacte JSON die verstuurd is of verstuurd gaat worden. Dit is de body waarover de handtekening berekend wordt, dus hiermee is een meningsverschil over een handtekening in één keer beslecht.

Nu opnieuw proberen

Zet deze bezorging terug in de wachtrij met een schone pogingenteller. Gebruik hem nadat het eindpunt gerepareerd is, of nadat uitgaande HTTP alsnog is toegestaan.

Nu bezorgen

Draait de bezorgronde meteen, voor elke bezorging die aan de beurt is.

Vijf pogingen, en dan stopt het

• Een bezorging wordt vijf keer geprobeerd, met 1, 5, 30 en 120 minuten ertussen. Daarna is ze gestrand en wacht ze op een mens.
• Alles anders dan een 2xx telt als mislukt, en een eindpunt dat binnen tien seconden niet antwoordt ook.
• Na twintig mislukkingen op rij zet een abonnement zichzelf uit. Dat getal staat op de CustomerGate-instellingen.
• Een abonnement dat zichzelf heeft uitgezet, komt nooit vanzelf terug. Repareer het eindpunt, kies Proefgebeurtenis versturen en daarna Aanzetten; gestrande bezorgingen haalt u terug met Nu opnieuw proberen.
• Een omgeving die uitgaande HTTP blokkeert, telt niet als mislukking van het eindpunt: dat is een instelling en geen kapotte ontvanger.
• Een proefgebeurtenis telt nooit mee en werkt ook op een abonnement dat uit staat.

Een boeking blijft er nooit op hangen

Een gebeurtenis die ontstaat terwijl er geboekt wordt, wordt in diezelfde transactie als rij in de wachtrij geschreven, en verder gebeurt er niets. Het bellen doet de bezorgtaak, elke vijf minuten. Een eindpunt dat traag is of stuk, kan een boeking dus nooit ophouden en nooit terugdraaien. Wordt de boeking zelf teruggedraaid, dan verdwijnt de rij mee.

Vertel de bouwer van de ontvangende kant twee dingen die hieruit volgen: verwacht dubbele berichten (een bezorging die bij u een time-out gaf, kan wel degelijk aangekomen zijn) en verwacht geen vaste volgorde (een opnieuw geprobeerde gebeurtenis komt binnen na gebeurtenissen die later plaatsvonden).

Wat er in een bericht staat, en wat niet

Een payload draagt kenmerken, standen, bedragen en datums, en geen persoonsgegevens: geen naam, geen e-mailadres, geen telefoonnummer, geen adres en geen vrije tekst. Dat is een regel van de app en geen gewoonte van deze versie; een toets faalt zodra een van die velden in een payload terechtkomt. Wie de naam achter een aanvraag nodig heeft, vraagt die met het nummer alsnog aan Business Central.

De twee webhooktabellen bevatten daarom zelf ook geen persoonsgegevens en worden door het opruimen en door het wissen per e-mailadres niet aangeraakt. Bezorgde en gestrande rijen verdwijnen na de Bewaartermijn webhooklogboek, standaard dertig dagen: dat is huishouding en geen bewaartermijn. Het geheim staat in isolated storage en nooit in een tabelveld, zodat het niet meereist in een export of een databasekopie.

Webhooks horen bij Complete

Webhooks zitten in het pakket Complete. Met een ander pakket komt er niets in de wachtrij en vertrekt er niets, hoe de abonnementen ook staan; Webhookabonnementen meldt dat bij het openen. Tijdens de proefperiode werken ze wel. Zie CustomerGate-licentie.