Introductie
In dit voorbeeld leer je hoe je met Invantive Cloud webhookberichten kunt ontvangen en verwerken. Aan de hand van Exact Online webhooks wordt dit geillustreerd, maar de beschreven werkwijze werkt ook voor bijvoorbeeld Teamleader Focus, ActiveCampaign of Brevo.
Exact Online Webhooks
Exact Online webhooks maken het mogelijk om near real-time meldingen te ontvangen wanneer er bepaalde gebeurtenissen plaatsvinden in een Exact Online-administratie. Bij een mutatie op Exact Online wordt automatisch en binnen enkele minuten informatie verstuurd naar een specifieke URL.
Alhoewel Exact Online webhooks incidenteel storingen hebben gehad de afgelopen jaren is het nog steeds de aanbevolen route om de bulk van mutaties te ontvangen voor data-integratie. Een eenvoudig voorbeeld is het bijwerken van een gekoppeld voorraadbeheersysteem zijn zodra een nieuwe verkooporder is geplaatst.
Verschillende top-level domeinnamen
De domeinnaam ontvangende URL van een webhook dient bij Exact Online gelijk te zijn aan de redirect URL. Aangezien Invantive App Online momenteel op https://app-online.cloud draait terwijl Invantive Cloud op https://cloud.invantive.com is een tussenlaag nodig.
Invantive biedt hiervoor de domeinnaam https://app-online-forward.invantive.com.
Deze forwarding leidt alle verzoeken die beginnen met /apps/ door naar Invantive App Online.
Er is daarnaast een tussenlaag nodig omdat de Exact Online webhookregistratie geen authenticatie kan meegeven aan de ontvangende URL.
In dit voorbeeld is daarom via Amazon CloudFront een proxy nodig die de authenticatie toevoegt:
- Maak een CloudFront distribution op basis van de origin
https://app-online-forward.invantive.com. - Voeg aan de origin een custom header toe voor de gewenste gebruikersnaam op Invantive Cloud:
De waarde valt te bepalen door de Invantive Cloud-gebruikersnaam en wachtwoord in het volgende UniversalSQL-statement in te vullen:
select base64_encode(ascii_to_blob('john.doe@acme.com' || ':' || 'secret'))
Applicatiemodule
Maak vervolgens een uitvoerbare PSQL-applicatiemodule met de volgende code aan. Deze code zal het bericht onvangen (zonder validatie met het webhooksecret) en een taak aanmaken in de Exact Online-administratie waar de gebeurtenis plaatsvond:
declare
l_payload clob;
l_nk varchar2;
begin
l_payload := cloud_http.get_request_body_text();
--
for r
in
( select *
from jsontable
( ''
passing l_payload
columns topic varchar2 path 'Content.Topic'
, clientid varchar2 path 'Content.ClientId'
, division int32 path 'Content.Division'
, action varchar2 path 'Content.Action'
, key guid path 'Content.Key'
, endpoint varchar2 path 'Content.ExactOnlineEndpoint'
, createdon datetime path 'Content.EventCreatedOn'
, hashcode varchar2 path 'HashCode'
)
)
loop
use select r.division, 'eol';
--
select act.name
into l_nk
from ExactOnlineREST..Accounts act
where id = r.key
;
insert into tasks@eol
( description
, notes
)
values
( 'EOL Webhook ' || to_char(sysdateutc, 'YYYYMMDDHH24MISS') || ' on ' || l_nk
, ''
|| 'Topic: ' || r.topic
|| chr(13) || 'Client ID: ' || r.clientid
|| chr(13) || 'Division: ' || r.division
|| chr(13) || 'Action: ' || r.action
|| chr(13) || 'Key: ' || r.key
|| chr(13) || 'Endpoint: ' || r.endpoint
|| chr(13) || 'Created: ' || to_char(r.createdon, 'DD-MM-YYYY HH24:MI:SS')
|| chr(13) || 'Payload: ' || l_payload
);
end loop;
end;
Registratie webhookabonnement
Start de applicatie waar de PSQL-applicatiemodule binnen valt. Kies “Kopieer link” op het kaartje en bewaar deze URL.
Open de database waar de webhookevents in geregistreerd moeten worden. Voer in de UniversalSQL-editor de volgende statements uit om het abonnement op berichten te registreren. Vervang hierbij https://voorbeeld...019d/ door de bewaarde link:
--
-- Kies gewenste Exact Online-administratie.
--
use 102673@eol
insert into webhooksubscriptions@eol
( CallbackURL
, Topic
, Description
)
values
( 'https://voorbeeld.invantive.com/apps/31175337-cf72-484d-bee6-798d41f0006d/databases/invantive-exact-online/modules/9c1dbb6f-a17b-4136-91d1-e4f3b63f019d/'
--
-- Ontvang berichten over relaties.
--
, 'Accounts'
, 'Sample'
)
Test de webhook
Zoek een relatie op in de Exact Online-administratie, en voer hierop een wijziging door zoals met:
set use-http-disk-cache false
set use-http-memory-cache false
update ExactOnlineREST..Accounts
set name = substr(to_char(sysdateutc, 'HH24MISS') || '.' || name, 1, 50)
--
-- Onderstaande code vervangen door bestaande relatiecode naar wens.
--
where code = '24261075'
Let op! Dit wijzigt de inhoud van Exact Online; de relatie krijgt een nieuwe naam met de kloktijd er in.
Wacht nu 3 minuten om Exact Online ruim de kans te geven het bericht af te leveren.
Kijk in Invantive App Online Monitoring of het bericht ontvangen is:
Het verzoek dient met een HTTP-statuscode 200 afgerond te zijn.
Controleer dat er een taak is aangemaakt in de Exact Online-administratie met de nieuwe naam van de relatie in de omschrijving (hier weggeveegd):
De payload van de webhookgebeurtenis op Exact Online bevat enkel technische informatie:
{"Content":{"Topic":"Accounts","ClientId":"07e0c93f-3cdd-425d-9e16-3785e1d72d3c","Division":102673,"Action":"Update","Key":"262386cb-bb3b-4c48-930d-001b0ac13558","ExactOnlineEndpoint":"https://start.exactonline.nl/api/v1/102673/crm/Accounts(guid'262386cb-bb3b-4c48-930d-001b0ac13558')","EventCreatedOn":"2024-06-27T15:20:30.643"},"HashCode":"A33E79A0A280BB2BBFC73180A774FCF47DA32D4DECB379BBCE9B72F262BFB913"}