Webhooks in CustomerGate 365

Zonder abonnement vertrekt er niets

Webhooks staan uit tot iemand in de Business Central-client een abonnement aanmaakt. Er is geen webservice die een abonnement kan aanmaken of lezen: het adres dat Business Central aanroept en het geheim waarmee het ondertekent, mag een website niet zelf kunnen instellen.

Hoe de ontvangende kant een handtekening controleert, met testwaarden om het zonder Business Central na te rekenen, staat in de naslag voor websitebouwers. Deze pagina beperkt zich tot de twee schermen.

De gebeurtenissen

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

Een order via medewerker 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. Ook de opruimtaak, die oude aanvragen op afgewezen zet terwijl ze de persoonsgegevens wist, meldt niets: anders zou het elke nacht berichten regenen over aanvragen van een jaar geleden.

Een abonnement instellen

1. Geef de app toestemming om überhaupt uitgaande aanroepen te doen: kies op de pagina Extensiebeheer CustomerGate 365, dan Configureren, en zet HttpClient-aanvragen toestaan aan. Zonder die instelling komt alles netjes in de wachtrij 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 geheim kan een abonnement niet worden aangezet.
5. Kies Proefgebeurtenis versturen. Die gaat meteen weg, en u ziet welke statuscode er terugkwam.
6. Zet de bezorgtaak op Gereed. Net als de mailtaak en de opruimtaak wordt hij met de status Afwachten aangemaakt; de knop Bezorgtaak opent hem.
7. Controleer op Webhookbezorgingen dat de proefgebeurtenis op Bezorgd staat.

De abonnementenlijst waarschuwt bovenaan als uitgaand HTTP-verkeer niet is toegestaan 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 wordt aangeroepen en waarom. De ontvanger ziet de code terug in de header X-VOA-Subscription, zodat één eindpunt meerdere abonnementen kan bedienen.

Eindpunt-URL

Het adres dat met POST wordt aangeroepen. Het moet met https beginnen en direct antwoorden: een doorverwijzing wordt niet gevolgd met de handtekeningheaders erbij.

Aan

Of er voor dit abonnement wordt bezorgd. Bij uitzetten strandt 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 niet meer vanzelf 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 is geprobeerd, wat er terugkwam (de statuscode en het begin van het antwoord) en wanneer de taak het weer mag proberen.

Documenttype, Documentnr., Klantnr.

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

Payload tonen

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

Nu opnieuw proberen

Zet deze bezorging terug in de wachtrij, met de pogingenteller weer op nul. Gebruik deze actie nadat het eindpunt is gerepareerd, of nadat uitgaand HTTP-verkeer alsnog is toegestaan.

Nu bezorgen

Voert de bezorgronde meteen uit, 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. Herstel het eindpunt, kies Proefgebeurtenis versturen en daarna Aanzetten; gestrande bezorgingen haalt u terug met Nu opnieuw proberen.
• Een omgeving die uitgaand HTTP-verkeer 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 uitstaat.

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 eindpunt wordt pas aangeroepen door de bezorgtaak, elke vijf minuten. Een traag of kapot eindpunt 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 bevat 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 test faalt zodra een van die velden in een payload terechtkomt. Wie de naam achter een aanvraag nodig heeft, vraagt die met het ontvangen nummer op in Business Central.

De twee webhooktabellen bevatten daarom zelf ook geen persoonsgegevens en worden door de opruimtaak en door het wissen per e-mailadres niet aangeraakt. Bezorgde en gestrande rijen verdwijnen na de Bewaartermijn webhooklogboek, standaard dertig dagen: dat is onderhoud 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.