Welke systemen? |
Het systeem waarnaar de gegevens verzonden moeten worden dient daar wel voor open te staan. Dat wil zeggen dat het gegevens moet kunnen ontvangen en verwerken. Voor het uitwisselen van gegevens worden verschillende methodieken gebruikt. Formdesk ondersteunt de volgende:
- HTTP GET
- HTTP POST
- HTTP PUT
- HTTP DELETE
- HTTP PATCH
Raadpleeg de documentatie van het systeem of neem contact op met de leverancier om te zien of één van bovenstaande methoden wordt ondersteund. U kunt ook bij ons een verzoek indienen om uit te laten zoeken of het systeem een ingang heeft voor de Formdesk webhook. |
|
|
Waar in te stellen |
|
Bij het bewerken van een formulier vindt u het webhook icoon aan de linkerkant van het Instellingen tabblad. Klik op 'Nieuwe webhook' om een webhook aan te maken. |
|
|
Voorgedefinieerde webhooks |
|
Formdesk biedt een aantal voorgedefinieerde webhooks met veel voorkomende systemen waaruit u kunt kiezen. Bekijk het overzicht van voorgedefinieerde webhooks en volg de daarbij behorende instructies. |
|
|
Algemene instellingen |
Indien u een voorgedefinieerde webhook selecteert dient u altijd nog aanpassingen te maken. Dit staat beschreven bij de toelichting.
Maakt u zelf een webhook, raadpleeg dan voor Methode (HTTP GET, POST, PUT, DELETE of PATCH), URL, eventuele headers en Authenticatie de documentatie van het systeem.
Heeft u meerdere webhooks dan kunt u hier ook de volgorde aangeven waarop de Webhooks worden uitgevoerd. |
|
|
 |
|
|
Data |
Bij het onderdeel Data kunt u aangeven welke gegevens u met de webhook wilt meezenden en, indien gewenst, hoe u een eventueel antwoord wilt verwerken.
Indien u voor de methode HTTP GET of HTTP POST PUT DELETE PATCH Form Data heeft gekozen kunt u een zogenaamde mapping aanmaken. U geeft hier per variabele van het andere systeem (parameter) aan welke invoer in uw formulier (waarde) daarbij hoort. De te gebruiken 'Parameters' vindt u in de documentatie van het systeem. De 'Waarde' kan een vaste waarde zijn, een verwijzing naar een invoer (Identifier), een systeemgegeven (systeem code) of een combinatie hiervan. Een voorbeeld: 'Ingevoerd per [_fd_Add] door [naam]'
|
 |
Indien u voor de methode HTTP POST PUT DELETE PATCH Raw payload heeft gekozen kunt u hier het bericht definiëren zoals het andere systeem deze wenst te ontvangen. Raadpleeg hiervoor de documentatie van het systeem. Een voorbeeld:
|
 |
Soms geeft een systeem bij het ontvangen van gegevens een antwoord. Bijvoorbeeld een uniek nummer waaronder de gegevens zijn opgeslagen. U kunt aangeven dat u dit antwoord opgeslagen wilt hebben in een tekst invoer die u desgewenst voor de invuller kunt verbergen. U ziet deze dan zelf wel in het overzicht van invoerresultaten en u kunt deze in een bericht aan de invuller tonen. Indien meerdere antwoorden worden gegeven in xml of json structuur, dan kunnen deze antwoorden in aparte Formdesk velden worden opgeslagen als de Identifiers van de vragen in het formulier overeen komen met de veldnamen in de antwoord. U selecteert dan de optie 'in velden met overeenkomstige Identifiers'.
|
 |
Indien het formulier de gebruiker toestaat bestanden mee te zenden en/of indien u een PDF bijlage heeft gedefinieerd dan kunnen deze ook worden verzonden met de webhook. Afhankelijk van de methode die u gebruikt kunt u volstaan met de identifier van de vraag of dient u de systeemcode [_fd_file(identifier)] te gebruiken. Raadpleeg hiervoor onderstaande tabel:
|
|
HTTP GET
Form data
|
HTTP POST PUT DETELE PATCH
Form data
|
HTTP POST PUT DETELE PATCH
Raw Payload
|
| Bestandcodering
|
Base64
|
Binair
|
|
Ge-upload bestand
|
| [Identifier]
|
Naam bestand
|
Naam en inhoud bestand
|
Naam en inhoud bestand
|
Naam bestand
|
| [_fd_file(identifier)]
|
N.v.t.
|
Inhoud bestand
|
N.v.t.
|
Inhoud bestand (Base64 encoded string)
|
PDF bijlage
|
| [_fd_pdf]
|
N.v.t.
|
Naam en inhoud bestand
|
Naam en inhoud bestand
|
Bestandsnaam
|
| [_fd_file(_fd_pdf)]
|
N.v.t.
|
Inhoud bestand
|
N.v.t.
|
Inhoud bestand (Base64 encoded string)
|
|
|
|
PDF bijlage |
Indien u voor de methode HTTP POST of HTTP XML heeft gekozen kunt u een document door de Formdesk PDF generator laten opstellen en meezenden naar het systeem. Net als bij de PDF bijlage bij de emailberichten kunt u hier antwoorden uit het formulier of zelfs het compleet ingevulde formulier in verwerken.
Indien u hier gebruik van maakt dient u bij het onderdeel Data aan te geven waarin het systeem dit PDF document dient te ontvangen. Raadpleeg hiertoe de tabel in hoofdstuk 'Data'. |
|
|
Verzend criteria |
Het kan heel goed zijn dat u niet in iedere situatie wilt dat de gegevens naar het andere systeem worden verzonden. Bijvoorbeeld als u in uw bestelformulier vraagt of men voortaan de nieuwsbrief wilt ontvangen wat u wilt koppelen met een email systeem. De webhook dient dan alleen uitgevoerd te worden als de invuller aangeeft de nieuwsbrief te willen ontvangen. Ook kan het zijn dat de webhook pas uitgevoerd mag worden nadat binnen de workflow het ingevulde formulier goedgekeurd is.
In deze situaties gebruikt u de verzend criteria om aan te geven wanneer de webhook uitgevoerd moet worden.
|
 |
|
|
Opnieuw uitvoeren |
|
Indien de webhook het andere systeem niet kan bereiken gaat Formdesk door met de normale afhandeling en zal de webhook niet worden uitgevoerd. U kunt echter altijd vanuit het overzicht van invoerresultaten de webhooks opnieuw uit laten voeren. Eventueel ingestelde verzend criteria zullen daarbij gerespecteerd worden. |
|
|
Webhooks en workflow |
Telkens als het formulier wordt verzonden, hetzij initieel, hetzij in de workflow, zal Formdesk eerst alle webhooks uitvoeren en daarna alle email berichten verzenden waarbij natuurlijk de verzend criteria worden gerespecteerd. Zo kunt u een webhook pas laten uitvoeren na een goedkeuring binnen de workflow of juist de workflow afhankelijk maken van het antwoord verkregen door de webhook.
Ook na de laatste workflow stap, wanneer de status van de invoer van 'Workflow te verzenden' wijzigt in 'Gereed', worden de webhooks nogmaals uitgevoerd. Indien u dus slechts één workflow bericht zou hebben zou de volgorde van uitvoeren als volgt zijn:
1. Initiële verzending door gebruiker
2. Webhooks uitvoeren
3. Workflow bericht uitvoeren
4. Webhooks uitvoeren
U kunt de status van de workflow opnemen in de verzendcriteria van de webhook. Bijvoorbeeld voor als u de webhook alleen uitgevoerd wilt hebben nadat de workflow geheel is voltooid. |
|
|
Beveiliging |
|
De gegevens zullen altijd versleuteld worden verstuurd (HTTPS).
Desgewenst kan een extra beveiliging laag worden toegepast door een encryptiesleutel op te geven bij het onderdeel Data. De ontvangende partij zal met deze sleutel de gegevens weer kunnen decrypten.
De toegepaste methode daarbij is AES256 mode GCM. De lengte van de sleutel moet dan ook 256 bits zijn of te wel 32 tekens. Bij deze methode wordt een Initialization Vector (IV) toegepast van 96 bits (12 tekens). Deze wordt door Formdesk telkens opnieuw gegenereerd en als prefix toegevoegd aan de versleutelde string.
Voor het decrypten moet dus de IV (1e 12 tekens) van de body worden gescheiden. De IV is nodig om samen met de encryptiesleutel het restant van de body te decrypten.
|
|
|
|
|
|
|
|