Webhooks

AM Systems utgående och inkommande webhooks möjliggör integration med externa tjänster. Genom att aktivera utgående webhooks i ett formulär kan du skicka data från ett ärende till ett externt system och genom aktivering av inkommande webhooks i ett formulär kan du skapa ett ärende från ett externt system.  För administratörer är det viktigt att känna till att alla fält som en inkommande webhook ska uppdatera måste ligga i ärendets första sektion samt att befintliga ärenden inte uppdateras.

Dessa webhooks fungerar lite på samma sätt som de triggers som finns i systemet, men för att aktivera webhooks krävs lite djupare tekniska kunskaper. Här rekommenderar vi att du som administratör tar kontakt med din IT-avdelning eller externa IT-partner när du vill aktivera webhooks i era formulär, om du inte själv redan är bekant med JSON.

Aktivering av webhooks gör du för varje formulär under fliken Avancerat och länken Addons. Här finns också information som din IT-avdelning eller externa IT-partner behöver för att kunna aktivera webhooks.

Utgående webhook

Med hjälp av ”Aktiveras när (When)” och ”Om följande villkor stämmer (if)” kan du kombinera flera händelser för att styra när en webhook ska skicka datat.

Under ”Innehåll”’ väljer du vilka fält från formuläret som du vill skicka med. Det finns även möjlighet att skapa egna fält för att möta det mottagande systemets krav.

Under ”Inställningar” anger man inställningar för det externa systemet.

HTTP method

POST, GET, PUT

Webhook URL

Det externa systemets URL

Autentiseringstyp

Basic, ingen

Försök

1, 2, 3

Timeout (sek)

10, 30, 60

Protokolltyp

Json, form

Om det externa systemet skickar ett eller flera svarsvärden finns det möjlighet att uppdatera fält i det aktuella ärendet med dessa värden. Detta gör du under ”Svarsdata”. Välj de fält som du vill ska uppdateras och under JSON ”Responsnyckel” anger du den svarsnyckel du fått av det externa systemet.

Inkommande webhook

För att skapa ett nytt ärende med en inkommande webhook måste det externa systemet veta vilken URL (webbadress) allt data ska skickas till samt vilka ”id” de fält som ska skapas har.

”Din Webhook URL”’ är den adress som det externa systemet ska använda.

”Fältens id” kan du hitta via ”Inställningar/ditt formulär” eller så kan du välja att ladda ner ’Formulärstruktur’.

Observera att fälten måste ligga i formulärets första sektion samt att befintliga ärenden inte uppdateras.

Under ’Skicka direkt som JSON’ hittar du exempel på en ”HTTP-post” som du kan testa genom att använda exempelvis cURL (ett enkelt verktyg för att skicka ”HTTP-requests” på kommandoraden). Ändra ”text- field” så att det motsvarar ett fält-id i ditt formulär.

curl -X POST -H ’Content-type: application/json’ \

–data ’{”text-field”: ”Simple input in a text-field with id textfield”}’ \

https://dinWebhookUrl

Autentisera användare
Om du vill autentisera användaren så aktiverar du på valet ”Autentisera användare”.

Du skapar en ”auth-nyckel” genom att i cURL ange:

curl -X POST -H ’Content-type: application/json’ \

–data ’{”username”: ”Username”, ”password”: ”Password”}’ \

https://dinWebhookUrl

Om användaruppgifterna är korrekta kommer du att få tillbaka en ”auth-nyckel” som du lägger till i ”Headern” som ”Auth-key”.

På motsvarande sätt kan du göra om du vill ta bort en auth-nyckel:

curl -X DELETE -H ’Content-type: application/json’ \

–data ’{”username”: ”Username”, ”password”: ”Password”}’ \

https://dinWebhookUrl

Validering

En inkommande webhook validerar att de fält som är obligatoriska i formuläret också finns med i allt inkommande data. Om du inte vill att den kontrollen ska ske, så kan du skicka med ”skipvalidate” i adressen:

https://dinWebhookUrl/skipvalidate

Triggers

Om formuläret är konfigurerat med triggers (automatiska aviseringar som sker vid specificerade händelser) och du inte vill att dessa triggers ska köras när en webhook skapar ett ärende, så kan du skicka med ”skiptriggers” i adressen:

https://dinWebhookUrl/skiptriggers

Skapare

Metadata ”Skapare” är ett obligatoriskt fält i alla formulär. Fältet uppdateras automatiskt med ”Incoming webhook” och behöver därför inte anges i JSON datat.

Hantera fel

Går allt bra får du svaret ” HTTP 200 OK” med ett tomt JSON objekt i ”bodyn”. I annat fall får du ett svar med ”HTTP 400 Bad Request” och en tillhörande JSON som talar om vad som gått fel.

Lista över vanliga fel

field_required

Fältet är obligatoriskt, data saknas

access_deny

Utfärdaren har inte rätt att registrera i detta formulär

wrong_date

Felaktigt datum

value_missing

Värdet saknas

value_not_array

Värdet är inte en array

value_not_numeric

Värdet är inte ett numeriskt


Alternativ

skipvalidate

Validering på obligatoriska fält sker ej (se avsnitt Validering)

skiptriggers

Triggers körs ej (se avsnitt Triggers)


Du kan kombinera ”skipvalidate” och ”skiptriggers”:

https://dinWebhookUrl/skiptriggers/skipvalidate

 

Upplevde du den här informationen som hjälpsam?

Din data, ditt val

AM System sparar ingen data om hur du navigerar på vår webbplats. Vi behöver dock spara cookies för att vissa sidor ska fungera. Datan är alltid anonym, och vi sparar så lite vi kan.

Jag förstår
Mer information