Webhooks Handleiding

Automatische notificaties naar externe systemen

Wat is een Webhook?

Een webhook stuurt automatisch data naar een extern systeem wanneer er iets verandert in je database. Dit is push-based: zodra er een INSERT, UPDATE of DELETE plaatsvindt op een tabel, verstuurt SQLio de data als JSON naar een door jou geconfigureerd endpoint. Het externe systeem hoeft dus niet zelf te pollen — de data wordt actief verstuurd.

Webhook aanmaken

Stap 1: Navigeer naar Webhook Configuratie

Klik in het menu op Webhook Configuratie. Je ziet een overzicht van alle bestaande webhooks.

Stap 2: Klik op "Nieuw"

Bovenaan verschijnt een formulier.

Stap 3: Basisinstellingen invullen

Stap 4: Trigger type kiezen

Kies wanneer de webhook moet afgaan:

Stap 5: Opslaan

Kies onderaan de bestemming: eerst de connectie en dan het endpoint (zie de handleiding Externe endpoints). Klik op Opslaan. SQLio maakt automatisch een database trigger aan op de gekozen tabel. Daarna configureer je de JSON body via de knop Request.

Veldcondities

Na het kiezen van een trigger type kun je bepalen onder welke voorwaarden de webhook afgaat. Klik op Veld toevoegen om condities toe te voegen.

Conditie-opties

Beschikbare condities

Conditie-types

Elke conditie kan twee soorten controle uitvoeren:

Voorbeeld: alleen triggeren bij statuswijziging naar "Verzonden"

De webhook gaat alleen af als het veld Status daadwerkelijk is gewijzigd EN de nieuwe waarde "Verzonden" is.

Voorbeeld: alleen triggeren voor klanten uit Nederland

De webhook gaat af bij elke wijziging, maar alleen als de klant uit Nederland komt.

JSON Request configureren

Klik op de JSON Request knop bij een webhook om te bepalen welke data wordt verstuurd.

Standaard velden

Je kunt de volgende metadata-velden aan- of uitzetten:

Per veld kun je de JSON veldnaam aanpassen. Bijvoorbeeld: table hernoemen naar tableName.

Custom velden

Voeg extra vaste velden toe die altijd worden meegestuurd:

Klik op Veld toevoegen om een nieuw custom veld aan te maken.

Dataset koppelen

Hier koppel je een dataset aan de webhook. De dataset bepaalt welke data als JSON body wordt verstuurd.

Zonder knooppuntnaam (merge)

De dataset-velden worden samengevoegd met de standaard/custom velden:

{
  "table": "dbo.Orders",
  "operation": "UPDATE",
  "orderId": 100,
  "orderDate": "2024-01-15",
  "customerName": "ACME Corp"
}

Met knooppuntnaam (genest)

De dataset-data wordt onder de opgegeven naam geplaatst:

{
  "table": "dbo.Orders",
  "operation": "UPDATE",
  "data": {
    "orderId": 100,
    "orderDate": "2024-01-15",
    "customerName": "ACME Corp"
  }
}

Alleen dataset (geen standaard/custom velden)

Als je geen standaard- en geen custom velden aanvinkt, wordt alleen de dataset-data verstuurd:

{
  "orderId": 100,
  "orderDate": "2024-01-15",
  "customerName": "ACME Corp"
}

Dataset parameter mapping

Als de gekoppelde dataset parameters heeft (bijv. een WHERE-conditie op :orderId), moet je instellen waar de waarde vandaan komt:

JSON Preview

Onderaan zie je een live preview van de JSON-structuur die verstuurd zal worden. Deze update automatisch als je instellingen wijzigt.

Endpoint en autorisatie

Endpoint selectie

Selecteer in het hoofdformulier bij Endpoint/Authorization het externe endpoint waarnaar de webhook data moet versturen. Dit endpoint bevat de URL en authenticatie-instellingen.

Ondersteunde authenticatie-methoden

OAuth 2.0

Bij OAuth 2.0 configureert de gebruiker:

Response verwerking

Optioneel kun je de response van het externe systeem terugschrijven naar je database.

Open de configuratie met de knop Response bij de webhook en zet Response verwerking inschakelen aan. Kies daarna hoe het antwoord verwerkt wordt:

Voorbeeld van zo'n procedure, die het zendingnummer uit het antwoord opslaat:

CREATE PROCEDURE dbo.prc_ZendingVerwerken
    @StatusCode int, @SuccesInd bit, @JsonBody nvarchar(max),
    @RequestJson nvarchar(max), @PrimaryKeyValue nvarchar(100)
AS
BEGIN
    SET NOCOUNT ON;
    IF @SuccesInd = 0 RETURN;
    UPDATE dbo.Verkooporders
       SET ZendingNr = JSON_VALUE(@JsonBody, '$.zendingNr')
     WHERE OrderNr = TRY_CAST(@PrimaryKeyValue AS int);
END
GO
GRANT EXECUTE ON dbo.prc_ZendingVerwerken TO SQLioRole;

Configuratie via interne API

1. Kies bij Verwerken via de optie Interne API
2. Selecteer het doel proces: een POST- of PATCH-endpoint dat is aangevinkt voor de databron van de webhook
3. Plak een voorbeeld JSON van de response die je verwacht
4. Klik op Velden detecteren — SQLio detecteert automatisch de velden

Response field mapping

Na het parsen zie je een tabel met gedetecteerde velden:

Mapping opties

Voorbeeld

Een webhook stuurt een order naar een extern systeem. Dat systeem retourneert een bevestigingsnummer:

{
  "confirmationId": "EXT-2024-0042",
  "status": "accepted"
}

Met response verwerking kun je dit confirmationId automatisch terugschrijven naar je eigen database via een PATCH API endpoint.

Verwerking en queue

Hoe de achtergrondservice werkt

SQLio controleert elke 30 seconden of er onverwerkte items in de webhook queue staan.

Rate limiting

SQLio verstuurt standaard maximaal 2 webhooks per seconde om externe API's niet te overbelasten. Dit is configureerbaar.

Retry logica

Als een webhook-call mislukt, probeert SQLio het automatisch opnieuw:

Circulaire triggers voorkomen

SQLio gebruikt CONTEXT_INFO() in SQL Server om te voorkomen dat een webhook-trigger zichzelf triggert. Als de webhook-respons data terugschrijft naar dezelfde tabel, wordt er geen nieuwe webhook afgevuurd.

Logging en monitoring

Webhook logs bekijken

Klik op de Log knop bij een webhook om de call-geschiedenis te zien.

Log tabel

Acties per log-regel

Log detail

Bij het uitklappen van een log-regel zie je:

• Configuration ID en Queue Item ID
• Tijdstempel en status code
• Primary key waarden
• Volledige response body

Log beheer

E-mail notificaties

Optioneel kun je e-mail notificaties inschakelen bij webhook-fouten:

1. Zet Notificaties aan bij de webhook
2. Selecteer de primaire ontvanger
3. Optioneel: voeg secundaire ontvangers toe
4. Bij een mislukte webhook-call ontvangen de geselecteerde personen een e-mail met foutdetails

Versioning

Elke webhook heeft een versie en optioneel versienotities:

Bij het opslaan kun je in een popup de versie bijwerken.

Webhook overzicht

In het overzicht zie je alle webhooks in een tabel:

Compleet voorbeeld: Order status webhook

Stel je wilt een extern CRM-systeem informeren wanneer een order de status "Verzonden" krijgt.

Stap 1: Maak een dataset aan

Maak eerst een dataset "Order gegevens" met de relevante orderdata (zie handleiding Datasets).

Stap 2: Maak de webhook aan

• Naam: Order Verzonden naar CRM
• Tabel: dbo.Orders
• Trigger type: Bij wijzigen van records (UPDATE)

Stap 3: Veldcondities

De webhook gaat alleen af als het veld Status daadwerkelijk wijzigt naar "Verzonden".

Stap 4: Endpoint/Authorization

Selecteer het geconfigureerde CRM endpoint met OAuth 2.0 authenticatie.

Stap 5: JSON Request configureren

1. Klik op JSON Request
2. Zet standaardvelden uit (geen metadata nodig)
3. Selecteer Data bron type: Dataset
4. Kies dataset: "Order gegevens"
5. Laat JSON Knooppunt Naam leeg (dataset data direct als root)
6. Map de dataset parameter orderId naar Parameter → newValue (de primary key van het gewijzigde record)

Stap 6: Opslaan en activeren

De webhook verstuurt nu automatisch de volgende JSON wanneer een order op "Verzonden" wordt gezet:

{
  "orderId": 100,
  "besteldatum": "2024-01-15",
  "klantnummer": "K001",
  "totaalbedrag": 74.50,
  "status": "Verzonden",
  "regels": [
    { "artikelNr": "A001", "aantal": 5, "stuksprijs": 12.50 },
    { "artikelNr": "A002", "aantal": 2, "stuksprijs": 8.00 }
  ],
  "klant": {
    "naam": "ACME Corp",
    "stad": "Amsterdam"
  }
}

Veelvoorkomende problemen