How To: Een AFAS-webhook gebruiken in U-Turn

Met een AFAS-webhook kan AFAS automatisch een bericht naar U-Turn sturen zodra een ingestelde gebeurtenis plaatsvindt. U-Turn kan vervolgens een of meer koppelingen uitvoeren.

Bijvoorbeeld:

Een dossieritem wordt gewijzigd in AFAS → AFAS stuurt een webhook → U-Turn ontvangt het bericht → U-Turn voert de gekoppelde koppeling uit.

Deze werkwijze is handig wanneer je gegevens direct wilt verwerken, zonder dat een koppeling voortdurend hoeft te controleren of er wijzigingen zijn.

Wat heb je nodig?

Voordat je begint, controleer je het volgende:

• De webhookfunctionaliteit is geactiveerd voor jouw U-Turn-omgeving.

• Je hebt toegang tot de juiste U-Turn-omgeving.

• Je hebt rechten om een berichtontvanger in U-Turn aan te maken of te wijzigen.

• Je hebt rechten in AFAS om een webhook in te richten.

• Je weet bij welke AFAS-gebeurtenis de koppeling moet starten, bijvoorbeeld:

  • een nieuw dossieritem;

  • een gewijzigd dossieritem;

  • een reactie;

  • een gebeurtenis in een workflow.

Hoe werkt de koppeling?

De verwerking bestaat uit twee delen:

1. U-Turn ontvangt het bericht.
   Hiervoor richt je in U-Turn een berichtontvanger in. De berichtontvanger bepaalt welke koppelingen worden gestart wanneer een bericht binnenkomt.

2. AFAS verstuurt het bericht.
   In AFAS richt je in bij welke gebeurtenis de webhook wordt verstuurd en naar welk U-Turn-endpoint dit gebeurt.

De volledige keten ziet er als volgt uit:

Gebeurtenis in AFAS
        ↓
AFAS verstuurt webhook
        ↓
U-Turn ontvangt bericht
        ↓
Berichtontvanger bepaalt de verwerking
        ↓
Gekoppelde U-Turn-koppeling(en) worden uitgevoerd

1. Richt de berichtontvanger in U-Turn in

Maak eerst in U-Turn een berichtontvanger aan en koppel hieraan de U-Turn-koppeling(en) die moeten worden uitgevoerd.

Volg hiervoor de stappen in het artikel:

Triggers: Berichtontvanger

In dit artikel lees je onder andere hoe je:

• naar het scherm Berichtontvangers gaat;

• een berichtontvanger toevoegt;

• de berichtontvanger een naam geeft;

• een of meer koppelingen selecteert;

• een bestaande berichtontvanger wijzigt.

Geef de berichtontvanger een herkenbare naam

Gebruik een naam waaruit duidelijk blijkt voor welke AFAS-gebeurtenis de berichtontvanger bedoeld is. Bijvoorbeeld:

• AFAS - dossieritem gewijzigd

• AFAS - nieuwe workflowtaak

• AFAS - dossier goedgekeurd

Een duidelijke naam helpt bij het beheren en testen van meerdere webhooks.

Let op het webhook-endpoint

Tijdens of na de inrichting in U-Turn is een endpoint beschikbaar dat je in AFAS nodig hebt. Neem dit endpoint volledig over.

Let daarbij op het volgende:

• Gebruik het endpoint van de juiste omgeving.

• Neem de URL over zonder spaties of regeleinden.

• Stel de URL niet zelf samen.

• Deel de URL niet openbaar wanneer deze een token bevat.

2. Kies de AFAS-gebeurtenis

Bepaal vervolgens in AFAS bij welke gebeurtenis de webhook moet worden verstuurd.

AFAS ondersteunt webhooks onder andere voor:

• dossieritems;

• reacties;

• workflows.

Voorbeelden:

• Een webhook versturen wanneer een dossieritem wordt aangemaakt.

• Een webhook versturen wanneer een dossieritem wordt gewijzigd.

• Een webhook versturen wanneer een reactie wordt toegevoegd.

• Een webhook versturen wanneer een workflowtaak een bepaalde status krijgt.

Kies de gebeurtenis zo specifiek mogelijk. Een te algemene gebeurtenis kan ervoor zorgen dat U-Turn berichten ontvangt die niet nodig zijn.

Voorbeeld

Je wilt een U-Turn-koppeling starten wanneer een declaratie wordt goedgekeurd. Richt de webhook dan in op de relevante workflowgebeurtenis, en niet op alle wijzigingen in AFAS.

3. Stel de webhook in AFAS in

Richt in AFAS een webhook in voor de gekozen gebeurtenis.

Gebruik hierbij het endpoint dat je tijdens de inrichting van de berichtontvanger in U-Turn hebt verkregen.

Controleer voordat je opslaat:

• of het volledige endpoint is ingevuld;

• of de webhook aan de juiste workflow, het juiste dossier of het juiste dossieritem is gekoppeld;

De precieze schermen en veldnamen kunnen verschillen per AFAS-versie en inrichting. Raadpleeg bij twijfel de AFAS-beheerder of de AFAS-documentatie.

Ik zou hoofdstuk 3 concreter maken door de daadwerkelijke AFAS-stappen te benoemen en de inrichting van de webhook los te trekken van het koppelen aan een dossieritem of workflow. Dat sluit aan op de actuele AFAS-documentatie. (AFAS Help Center)

1. Ga in AFAS Profit naar Algemeen → Beheer → App connector en open de app connector die voor U-Turn wordt gebruikt.

2. Open het tabblad Webhooks en klik op Nieuw.
   

   

3. Vul bij Omschrijving een herkenbare naam in, bijvoorbeeld U-Turn - Dossieritem gewijzigd.

4. Vul bij URL het webhook-endpoint in dat in U-Turn bij de berichtontvanger beschikbaar is. Gebruik het endpoint van de juiste U-Turn-omgeving en neem de URL volledig over. AFAS vereist een publiek bereikbaar HTTPS-endpoint. (AFAS Help Center)

5. Vul bij Wachtwoord het webhook-wachtwoord in. Gebruik bij voorkeur een sterk, uniek wachtwoord. AFAS gebruikt dit wachtwoord voor de beveiliging van de webhook-notificaties. (AFAS Help Center)

6. Klik op Voltooien om de webhook op te slaan.

7. Open de eigenschappen van de zojuist aangemaakte webhook en kies Acties → Verstuur testbericht.

8. Controleer in U-Turn of het testbericht is ontvangen. Hiermee controleer je direct of het endpoint correct is ingesteld en bereikbaar is.

9. Controleer in AFAS bij de webhook op het tabblad Events of het testbericht succesvol is verwerkt. Bij een fout kun je hier ook aanvullende informatie over de aflevering bekijken. (AFAS Help Center)

10. Koppel de webhook vervolgens aan de gewenste gebeurtenis:

    • Dossieritem: ga naar CRM → Dossier → Inrichting → Type dossieritem → Webhooks en kies welke acties de webhook moeten activeren, bijvoorbeeld toevoegen, wijzigen of verwijderen.

    • Workflow: open de betreffende workflow en koppel de webhook aan de gewenste workflowtaak of -actie. Publiceer daarna de workflow. (AFAS Help Center)

11. Voer tot slot één gecontroleerde test uit met het gekozen dossieritem of de gekozen workflow. Controleer of AFAS → U-Turn → berichtontvanger → gekoppelde koppeling volledig wordt doorlopen. (Mooqe Help)

Belangrijk: een AFAS-webhook bevat in veel gevallen alleen de melding dát iets is gewijzigd en niet alle gewijzigde gegevens. De U-Turn-koppeling kan daarom aanvullende gegevens uit AFAS moeten ophalen. (AFAS Help Center)

Gebruik voor de AFAS-inrichting de actuele documentatie van AFAS:

• Webhooks op dossier- en workflowgebeurtenissen

• AFAS Profit 8 – Webhooks

• Technische documentatie AFAS-webhooks

4. Controleer de rechten in AFAS

De AFAS-gebruiker of configuratie waarmee de webhook wordt uitgevoerd, moet toegang hebben tot de relevante gegevens.

Controleer onder andere de rechten voor:

• het betreffende dossier;

• het dossieritem;

• de workflowtaak;

• de gebruikte connector;

• de gegevens die door de U-Turn-koppeling moeten worden gelezen of gewijzigd.

Een webhook kan wel bij U-Turn aankomen, terwijl de daaropvolgende koppeling toch mislukt door ontbrekende AFAS-rechten.

5. Test de webhook

Test de inrichting eerst met één gecontroleerde wijziging.

1. Gebruik bij voorkeur een acceptatieomgeving.

2. Kies één testdossier of testworkflow.

3. Voer de AFAS-actie uit die de webhook moet activeren.

4. Controleer of AFAS het bericht heeft verstuurd.

5. Controleer of U-Turn het bericht heeft ontvangen.

6. Controleer of de koppeling uit de berichtontvanger is gestart.

7. Controleer het resultaat van de koppeling.

Controleer ook of het ontvangen bericht voldoende informatie bevat voor de koppeling. Een webhookbericht is mogelijk vooral een melding dat er iets is gewijzigd. Het kan daarom nodig zijn dat de U-Turn-koppeling aanvullende gegevens uit AFAS ophaalt.

Activeer de webhook pas voor alle dossiers of workflows nadat de test succesvol is afgerond.

6. Inrichting U-Turn koppeling

Nadat de webhook in AFAS en de berichtontvanger in U-Turn zijn ingericht, kan de U-Turn-koppeling worden ingericht op basis van de gegevens uit de webhook.

Een AFAS-webhookbericht bevat een vaste basisstructuur. De inhoud van Data verschilt per gebeurtenis.

Opbouw van het webhookbericht

{
  "EventId": "<unieke-event-id>",
  "EnvironmentId": "<AFAS-omgeving>",
  "EventType": "<type-gebeurtenis>",
  "Data": {},
  "Timestamp": "<tijdstip-in-utc>"
}

De belangrijkste velden zijn:

Gebruik bij het inrichten van de koppeling vooral EventType en de velden binnen Data. De payload bevat mogelijk niet alle gegevens die de koppeling nodig heeft. In dat geval kunnen de ontvangen identifiers worden gebruikt om aanvullende gegevens uit AFAS op te halen.

Voorbeeld: workflowactie uitgevoerd

Wanneer er een testbericht vanuit de AFAS webhook inrichting wordt verstuurd, kan AFAS bijvoorbeeld het volgende bericht versturen:

{
  "EventId": "79d9b863-627b-497f-861e-147503472e8d",
  "EnvironmentId": "12345AA",
  "EventType": "test.executed",
  "Data": {
    "SubscriptionId": 1,
    "SubscriptionName": "Webshop"
  },
  "Timestamp": "2026-06-08T09:20:56.1351565Z"
}

In dit voorbeeld kan de koppeling de volgende gegevens gebruiken:

• EventType om te controleren of het juiste type gebeurtenis is ontvangen;

• SubscriptionId om de subscription te identificeren;

• SubscriptionName om de subscription herkenbaar te maken in de verdere verwerking.

Voorbeeld: workflowtaak betreden

Wanneer een workflowtaak wordt betreden, kan het eventtype verschillen:

{
  "EventId": "79d9b863-627b-497f-861e-147503472e8d",
  "EnvironmentId": "12345AA",
  "EventType": "workflow.task.entered",
  "Data": {
    "SubjectTypeId": 123,
    "SubjectId": 456789,
    "WorkflowName": "2448365B41A82343F00FC89A8EFDB394",
    "TaskName": "5B8D2A7C1E4F4B6A9C123456789ABCDE"
  },
  "Timestamp": "2026-09-11T08:55:32.1234567Z"
}

De koppeling kan in dit geval gebruikmaken van:

• EventType om te controleren of een workflowtaak is betreden;

• SubjectTypeId om het type AFAS-object te bepalen;

• SubjectId om het specifieke AFAS-object te identificeren;

• WorkflowName om de workflow te herkennen;

• TaskName om de workflowtaak te herkennen.

SubjectTypeId en SubjectId moeten samen worden gebruikt om het juiste object in AFAS te bepalen. Wanneer de webhook alleen deze identifiers bevat, kan de koppeling aanvullende gegevens uit AFAS ophalen voordat de verdere verwerking wordt uitgevoerd.

Testdata gebruiken in het bouwblok

Voer eerst de AFAS-gebeurtenis uit waarvoor de webhook is ingericht. Controleer vervolgens in U-Turn of het webhookbericht is ontvangen.

De testdata kan worden gebruikt om de U-Turn-koppeling verder in te richten:

De beschikbare velden zijn afhankelijk van het ontvangen eventtype. Bij test.executed zijn bijvoorbeeld SubscriptionId en SubscriptionName beschikbaar. Bij workflow.task.entered zijn onder andere SubjectTypeId, SubjectId, WorkflowName en TaskName beschikbaar.

Na het opslaan zal het bouwblok kolommen beschikbaar stellen die in de vervolgblokken te gebruiken zijn:

Gebruik de testdata bijvoorbeeld om:

• een waarde uit de webhook door te geven aan een volgend bouwblok;

• op basis van EventType een bepaalde verwerking uit te voeren;

• op basis van WorkflowName of TaskName een workflow te herkennen;

• met SubjectTypeId en SubjectId aanvullende gegevens uit AFAS op te halen;

• een ontvangen identifier te gebruiken in een AFAS-connector of andere koppeling.

Controleer na het configureren of de waarden uit de testdata op de juiste plek in de koppeling worden gebruikt. Test de volledige koppeling daarna opnieuw met een nieuwe gebeurtenis in AFAS.

Let op: de beschikbare velden in Data kunnen per AFAS-event verschillen. Gebruik daarom alleen velden die in het ontvangen testbericht aanwezig zijn. De payloadvoorbeelden in dit artikel dienen als voorbeeld; controleer de daadwerkelijke payload in de eigen U-Turn-omgeving.

Gegevens ophalen

Nu de gegevens uit het webhook bericht beschikbaar zijn, kunnen deze in een volgend bouwblok gebruikt worden. Bijvoorbeeld met een “AFAS Profit Ophalen“ bouwblok:

Hierin kan er gefilterd worden op de data uit het webhook bericht. Onderstaand voorbeeld is ter illustratie. Het zal in de praktijk niet voorkomen dat het SubjectId uit de webhook zal corresponderen met een Dossieritem nummer.

Veelvoorkomende problemen

De berichtontvanger is niet beschikbaar in U-Turn

Mogelijke oorzaken:

• je werkt in de verkeerde omgeving;

• de webhookfunctionaliteit is niet geactiveerd;

• je hebt onvoldoende rechten;

• de berichtontvanger is verwijderd of aangepast.

Controleer eerst de omgeving en je rechten. Vraag zo nodig de U-Turn-beheerder om de webhookfunctionaliteit te controleren.

AFAS verstuurt geen webhook

Controleer:

• of de webhook actief is;

• of de gekozen AFAS-gebeurtenis daadwerkelijk heeft plaatsgevonden;

• of de webhook aan de juiste workflow of het juiste dossier is gekoppeld;

• of het endpoint exact is overgenomen;

• of AFAS een foutmelding geeft bij het afleveren;

• of de AFAS-omgeving verbinding kan maken met het U-Turn-endpoint.

Controleer ook of de uitgevoerde actie een gebeurtenis is waarvoor AFAS webhooks ondersteunt.

U-Turn ontvangt het bericht, maar voert geen koppeling uit

Controleer:

• of de U-Turn koppeling gepubliceerd is;

• of de juiste berichtontvanger is gebruikt;

• of aan deze berichtontvanger minimaal één koppeling is gekoppeld;

• of de gekoppelde koppeling actief is;

• of de koppeling zelfstandig werkt;

• of de berichtontvanger bij de juiste omgeving hoort.

Gebruik herkenbare namen voor berichtontvangers en koppelingen om vergissingen te voorkomen.

De koppeling geeft een autorisatie- of rechtenfout

Controleer in AFAS of de gebruikte gebruiker rechten heeft op:

• het dossier;

• het dossieritem;

• de workflowtaak;

• de gebruikte connector;

• de gegevens die de koppeling moet lezen of wijzigen.

Laat deze controle uitvoeren door een AFAS-beheerder als je zelf niet over de benodigde rechten beschikt.

Dezelfde wijziging wordt meerdere keren verwerkt

Een webhook kan opnieuw worden aangeboden wanneer de ontvangende partij tijdelijk niet beschikbaar is of wanneer de afhandeling niet succesvol is afgerond.

Correctie kan worden toegepast op basis van:

• hoe dubbele berichten worden herkend;

• hoe foutafhandeling is ingericht;

• hoe je een mislukte verwerking terugvindt;

• of een bericht opnieuw kan worden verwerkt.

Controleer vooral bij koppelingen die documenten aanmaken, berichten versturen of gegevens wijzigen of dubbele verwerking geen ongewenste gevolgen heeft.

Beveiliging en beheer

Behandel het webhook-endpoint als vertrouwelijke informatie wanneer hierin een token of andere identificatie is opgenomen.

• Deel het endpoint niet openbaar.

• Gebruik per omgeving het juiste endpoint.

• Controleer of acceptatie niet naar productie verwijst.

• Vervang het endpoint wanneer het mogelijk openbaar is geworden.

• Verwijder niet meer gebruikte webhookconfiguraties uit AFAS.

• Leg vast waarvoor elke berichtontvanger en webhook wordt gebruikt.

Houd daarnaast bij:

• de naam van de berichtontvanger;

• de AFAS-gebeurtenis;

• de gebruikte workflow of het dossier;

• de gekoppelde U-Turn-koppeling(en);

• de omgeving;

• de datum van de laatste test;

• de verantwoordelijke beheerder.

Voorbeeld

Een organisatie wil automatisch een U-Turn-koppeling starten zodra een dossier in AFAS de status Goedgekeurd krijgt.

De inrichting is dan als volgt:

1. In U-Turn maak je volgens het artikel Triggers: Berichtontvanger een berichtontvanger aan met de naam:

   • AFAS - dossier goedgekeurd

2. Je selecteert de koppeling die het goedgekeurde dossier moet verwerken.

3. Je neemt het U-Turn-endpoint over.

4. In AFAS richt je een webhook in op de relevante dossierworkflow.

5. Je stelt in dat de webhook wordt verstuurd wanneer het dossier de status Goedgekeurd krijgt.

6. Je test dit met één testdossier.

7. Na een succesvolle test activeer je de inrichting voor de gewenste dossiers.

Samenvatting

Een AFAS-webhook gebruiken in U-Turn bestaat uit de volgende hoofdlijnen:

1. Richt in U-Turn een berichtontvanger in volgens het artikel Triggers: Berichtontvanger.

2. Koppel de gewenste U-Turn-koppeling(en) aan de berichtontvanger.

3. Noteer het bijbehorende webhook-endpoint.

4. Kies in AFAS de gebeurtenis die de webhook moet activeren.

5. Richt de webhook in AFAS in met het U-Turn-endpoint.

6. Controleer de AFAS-rechten.

7. Test de volledige verwerking met één gecontroleerde wijziging.

Bronnen

• U-Turn: Triggers – Berichtontvanger

• AFAS: Webhooks op dossier- en workflowgebeurtenissen

• AFAS Profit 8: Webhooks

• AFAS technische documentatie: webhooks