En webhook är en teknisk funktion som kan används för att skicka data i realtid. Webhooks är användbara för att uppdatera information på olika platser utan manuell inblandning.
|
Observera att denna funktion är en tilläggstjänst som ingår i vissa prisplaner, men kan också köpas separat. Kostnaden är då 350 SEK / månad och registreras på kommande faktura. Om du har frågor om din prisplan eller vill aktivera funktionen, vänligen kontakta sales@amsystem.com. |
Inledning
AM Systems funktionalitet för att kommunicera med externa tjänster och system erbjuds i form av webhooks. Webhooks är inget unikt för AM System utan kan ses som ett ramverk för att skicka och ta emot data mellan olika tjänster och system. Tänk på webhhoks som en automatiserad funktion som kan ersätta att en person kopierar data från ett system till ett annat.
Webhooks består av två komponenter, utgående respektive inkommande webhooks
Utgående Webhook
Utgående Webohook gör det möjligt att skicka specificerad data under vissa angivna premisser. I denna utgående Webhook kan man även definiera ett eventuellt svar som det externa systemet kan ge. Svaret kan sedan sparas i samma ärende som initierade den utgående webhooken.
Exempelvis kan man skicka utvald ärende- och metadata när ett ärende skapas till ett externt system som har stöd för Webhooks. Det externa systemet kan då ta emot denna data och eventuellt ge ett svar. Skulle samma ärende trigga en ny Webhook så skickas data på nytt, MEN det är upp till mottagande system att hantera detta som en uppdatering av data (genom att exempelvis jämföra en konstant variabel som ärendenummer) då den utgående webhooken inte i sig inte tar hänsyn till om det är ny eller uppdaterad data.
Inkommande Webhook
Inkommande Webhook har omvänd funktionalitet, det vill säga att en inkommande Webhook är ett enkelt sätt att registrera in ärenden från externa tjänster och system till AM System och ett specifik formulär. Inkommande Webhook handlar alltså om en envägskommunikation och varje inkommande Webhook kommer att skapa ett nytt ärende.
Observera att en inkommande Webkook INTE kan:
- Ge externt system något retursvar på den inkommande webhooken
- Användas för att ställa en fråga som exempelvis "Ge mig alla ärenden med ärendenummer mellan #28 och #36
- Uppdatera data i ett redan skapat ärende.
- Skapa data i andra sektioner än den första (översta sektionen i ett formulär)
Så aktiveras Webhooks
Att aktivera Webhooks är i sig enkelt då de aktiveras på samma sätt som meddelande-triggers och påminner därför även om hur dessa hanteras. Aktivering av webhooks gör du för varje formulär under fliken Avancerat och Addons » Mera addons ... » Utgående Webhook eller Inkommande Webhook. Här finns också information som din IT-avdelning eller externa IT-partner behöver för att kunna aktivera webhooks.
För att konfigurera 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 konfigurera Webhooks i era formulär, om du inte själv redan är bekant med Webhooks.
Teknisk sammanfattning för dig som vill utforska Webhooks själv!
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 data.
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 du inställningar för det externa systemet som exempelvis HTTP Method och Autentiseringstyp.
| 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, JSON ARRAY, 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"}' \
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"}' \
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"}' \
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 "Addon - Inkommande 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":
Tredjepartstjänster
Två exempel på verktyg som kan vara till hjälp för att hantera Webohoks är https://zapier.com, samt https://webhook.site. Observera att AM System inte har något samarbete med dessa tjänster och AM System tar därmed inte något ansvar för dessa tjänster eller hur de används!
Senast uppdaterad: 8 maj, 2024