Dit artikel legt je de ins en outs uit van het trigger type 'binnenkomende webhook' waarmee je Neoforce aan andere software kunt koppelen.

Wat is een inkomende webhook

Met een inkomende webhook registreer je een unieke URL binnen jouw Neoforce-omgeving die je kunt koppelen aan andere applicaties of systemen.

Wanneer een extern systeem een HTTP-request naar de Neoforce-webhook-URL stuurt, kan Neoforce specifieke acties uitvoeren, zoals het aanmaken van tickets, het bijwerken van assets, of het activeren van workflows. Dit biedt een krachtige manier om processen te automatiseren en data uit verschillende bronnen in Neoforce samen te brengen.

Bovendien kun je met behulp van filters en voorwaarden de inkomende webhooks zo configureren dat ze alleen worden verwerkt als aan bepaalde criteria is voldaan, waardoor je maximale controle hebt over hoe en wanneer deze acties worden uitgevoerd.

Type requests

Inkomende webhooks in Neoforce ondersteunen zowel GET- als POST-verzoeken.

• GET-verzoeken: Bij een GET-verzoek wordt de trigger zonder extra opties direct 'afgevuurd'. DIt is handig voor simpele acties waarbij je geen data hoeft door te sturen e.d.
• POST-verzoeken: Bij een POST-verzoek worden gegevens in de body van het verzoek verzonden, meestal in de vorm van een JSON-object. Neoforce kan deze JSON-body interpreteren en de daarin opgenomen gegevens verwerken.
  Dit betekent dat je complexe data kunt doorsturen, die vervolgens als variabelen in Neoforce kunnen worden gebruikt om diverse acties uit te voeren. Zo kun je bijvoorbeeld de ontvangen data gebruiken om een nieuw ticket aan te maken, een asset te updaten, of een workflow te starten. Door de flexibiliteit van JSON kan Neoforce dynamisch reageren op een breed scala aan input, waardoor je uitgebreide automatiseringsscenario's kunt implementeren. Verder kun je deze data gebruiken als 'filter'.

Gebruik van webhooks

1. Het eerste wat je moet controleren is of de software waarmee je wilt integreren, ondersteuning biedt voor uitgaande webhooks. Dit betekent dat de software automatisch informatie kan versturen naar een andere applicatie, zoals Neoforce, wanneer er iets gebeurt, bijvoorbeeld wanneer een nieuw record wordt aangemaakt. Deze instellingen worden meestal gevonden onder de naam 'webhooks' of 'integraties'. Je hebt minimaal een veld nodig om een URL in te plakken.

2. Zodra je deze optie hebt gevonden, moet je een nieuwe inkomende webhook aanmaken in Neoforce. Dit doe je door in Neoforce een webhook te registreren, wat een unieke URL oplevert. Deze URL plak je vervolgens in de instellingen van de andere software. Telkens wanneer er een relevante gebeurtenis plaatsvindt in die software, zal deze een bericht sturen naar Neoforce via de URL. Later in dit artikel vind je gedetailleerde instructies over hoe je een inkomende webhook in Neoforce registreert.

3. Nadat de webhook is ingesteld, kun je in Neoforce één of meerdere acties koppelen aan de trigger die door de webhook wordt geactiveerd. Bijvoorbeeld, wanneer er nieuwe data binnenkomt, kan Neoforce automatisch een ticket aanmaken, een asset updaten, of een andere geautomatiseerde taak uitvoeren. Je kunt ook voorwaarden toevoegen, zodat deze acties alleen plaatsvinden als aan bepaalde criteria wordt voldaan, zoals specifieke data-inhoud of het tijdstip van de gebeurtenis. Dit maakt het mogelijk om je workflows precies af te stemmen op wat jouw organisatie nodig heeft.

Nieuwe inkomende webhook registeren

1. Klik rechtsboven op je naam en kies voor 'Beheer'.
2. Ga in het linkermenu, onder 'Applicatie/algemeen' naar 'Triggers en acties'.
   
3. Klik nu op het tabblad 'Triggers'.
4. Klik vervolgens op '[Nieuw]'.
5. Vul minimaal een naam en type trigger in.
   
   ➡️ Voor deze trigger dien je het type 'Webhook ontvangen' te kiezen.
   
6. Na het opslaan van de nieuwe trigger zul je zien dat er een unieke URL gegenereerd wordt. Deze URL plak je op de betreffende plek in de andere applicatie.
   

Uitgebreide(re) data gebruiken

Het hoofdstuk hierboven beschrijft hoe je met behulp van een webhook simpelweg iets 'start'. Naast deze simpele manier kun je echter ook data meesturen en deze gebruiken in Neoforce.

• Neoforce biedt momenteel alleen ondersteuning voor JSON. Het is dus van belang dat de externe applicatie de data in de body van het verzoek verstuurd (als POST).
• Alle -door Neoforce interpreteerbare- data wordt omgezet naar een variabele, voorzien van de prefix body. Daarna volgt de 'key' van de JSON-array.

Voorbeeld

In dit voorbeeld simuleren we externe software die de onderstaande JSON-array (als POST!) stuurt:

{
    "name":"John",
    "age":30,
    "car": "BMW",
    "properties": {
        "eyecolor": "blue",
        "haircolor": "blonde"
  }
}

Deze 'body' genereert de volgende variabelen die je -zoals altijd- kunt gebruiken binnen een actie of binnen de voorwaarden van deze trigger:

Gebruik van (Sub)arrays

In het bovenstaande voorbeeld zie je dat de JSON-structuur ook een geneste (sub)array bevat, namelijk properties. Neoforce ondersteunt het gebruik van dergelijke geneste gegevensstructuren. Elke laag in de array wordt aangeduid door een puntnotatie. Dit betekent dat je binnen acties en voorwaarden direct toegang hebt tot specifieke gegevens in geneste objecten.

Bijvoorbeeld:

• Voor de oogkleur van de persoon gebruik je de variabele ${body.properties.eyecolor}, wat in dit geval de waarde "blue" oplevert.
• Op dezelfde manier kun je met ${body.properties.haircolor} de haarkleur "blonde" ophalen.