> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outkept.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Stuur phishingevents in realtime naar je eigen endpoint.

Met webhooks stuurt het platform in realtime meldingen van events naar een systeem van jouw
keuze. Telkens er een relevant event plaatsvindt, bijvoorbeeld een gebruiker die op een
simulatielink klikt of een simulatie rapporteert, sturen we een HTTP POST-request met
gestructureerde eventdata naar een URL die jij instelt.

Zo koppel je het platform aan je eigen tooling, zoals een SIEM, een HR-systeem, een
ticketsysteem of een eigen dashboard, zonder een API te moeten pollen.

## Ondersteunde events

| Eventtype | Wanneer het afgaat |
| - | - |
| `phishing.opened` | Een gebruiker opende een simulatiemail |
| `phishing.clicked` | Een gebruiker klikte op de phishinglink in een simulatiemail |
| `phishing.attachment_opened` | Een gebruiker opende een bijlage van een simulatiemail |
| `phishing.data_submitted` | Een gebruiker gaf gegevens in op een phishinglandingspagina |
| `phishing.replied` | Een gebruiker antwoordde op een simulatiemail |
| `phishing.reported` | Een gebruiker rapporteerde de simulatiemail via de rapporteerknop |

Al deze events worden naar je endpoint gestuurd. Je kunt je niet op een deel ervan abonneren.

<Note>
  Enkel de eerste keer dat een event zich voordoet, wordt het verstuurd. Klikt een gebruiker
  twee keer op dezelfde simulatie, dan krijg je één `phishing.clicked`-event. Botevents worden
  nooit verstuurd.
</Note>

## Voor je begint

Je hebt nodig:

* Toegang tot het platform met de rol **Administrator** of **Partner**
* Een publiek bereikbaar HTTPS-endpoint dat POST-requests kan ontvangen

<Warning>
  Endpoints zonder TLS worden niet ondersteund. De URL moet `https://` zijn.
</Warning>

## Een webhook toevoegen

<Steps>
  <Step title="Open de webhookinstellingen">
    Ga naar **Settings**, dan **Integrations** en dan **Webhooks**.
  </Step>

  <Step title="Voeg de webhook toe">
    Klik op **Add webhook** en vul je endpoint-URL in. Dat moet een geldige, publiek
    bereikbare `https://`-URL zijn.
  </Step>

  <Step title="Bevestig">
    Klik op **Add webhook** om op te slaan.
  </Step>

  <Step title="Kopieer het signing secret">
    Er verschijnt een signing secret. Kopieer het meteen en klik daarna op **I've copied the
    secret**.
  </Step>
</Steps>

<Warning>
  Het signing secret wordt één keer getoond en kan later niet meer opgevraagd worden. Bewaar
  het veilig voor je het venster sluit.
</Warning>

Om de integratie te testen, stuur je een testmail via **Emails** en dan **Tests**, en
interageer je ermee.

## Eventpayload

Events worden als JSON afgeleverd in de body van een HTTP POST-request.

| Header | Waarde |
| - | - |
| `Content-Type` | `application/json` |
| `X-Signature` | HMAC-SHA256-handtekening van de payload, zie [Echtheid controleren](#echtheid-controleren) |
| `X-Signature-Timestamp` | Tijdstip waarop de request ondertekend werd |

Voorbeeldpayload:

```json theme={null}
{
  "event_type": "phishing.clicked",
  "email": "test@outkept.com",
  "source": "OutKept",
  "timestamp": "2026-06-09T14:30:45.123Z",
  "nonce": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}
```

| Veld | Wat erin zit |
| - | - |
| `event_type` | Het type event, uit de tabel hierboven |
| `email` | E-mailadres van de persoon die de actie deed |
| `source` | Altijd `OutKept` |
| `timestamp` | ISO 8601-datumstring van wanneer het event plaatsvond |
| `nonce` | Willekeurige UUID, gebruik die om binnenkomende requests te ontdubbelen |

## Echtheid controleren

Elke request bevat een `X-Signature`-header. Dat is een HMAC-SHA256-handtekening, berekend over
de ruwe request-body met jouw signing secret als sleutel.

<Steps>
  <Step title="Lees de ruwe body">
    Neem de ruwe request-body, voor je de JSON parst.
  </Step>

  <Step title="Bereken de handtekening">
    Bereken HMAC-SHA256 over de ruwe body met je signing secret.
  </Step>

  <Step title="Vergelijk">
    Vergelijk je resultaat met de waarde in de `X-Signature`-header.
  </Step>

  <Step title="Aanvaard of weiger">
    Komen ze overeen, dan is de request echt en kun je ze verwerken. Komen ze niet overeen,
    weiger ze dan met een 401-respons.
  </Step>
</Steps>

<Warning>
  Gebruik altijd een timing-safe vergelijkingsfunctie. Een gewone stringvergelijking lekt
  informatie via de uitvoeringstijd en kan gebruikt worden om een handtekening te vervalsen.
</Warning>

## Nieuwe pogingen

Geeft je endpoint binnen 10 seconden geen HTTP 2xx-respons, dan wordt de aflevering
automatisch opnieuw geprobeerd. Na 5 mislukte pogingen wordt de aflevering als **Failed**
gemarkeerd.

## Een webhook verwijderen

<Steps>
  <Step title="Open de webhookinstellingen">
    Ga naar **Settings**, dan **Integrations** en dan **Webhooks**.
  </Step>

  <Step title="Verwijder ze">
    Klik op **Delete webhook** en bevestig in het venster.
  </Step>
</Steps>

Een webhook verwijderen stopt alle verdere afleveringen. Events die plaatsvinden terwijl er
geen webhook actief is, worden niet bewaard en ook niet achteraf alsnog afgeleverd.

## Problemen oplossen

| Probleem | Oplossing |
| - | - |
| Testevent komt niet aan | Controleer of het endpoint publiek bereikbaar is via HTTPS en een 2xx-status teruggeeft |
| Handtekeningcontrole mislukt | Bereken de HMAC over de ruwe, ongeparste request-body in plaats van over de geparste JSON |
| Endpoint loopt in timeout | Antwoord meteen met 200 en verwerk de payload asynchroon, zodat je binnen de 10 seconden blijft |
| Dubbele events | Gebruik de `nonce` in de body om binnenkomende requests te ontdubbelen |

Voor alles wat hier niet vermeld staat, contacteer
[support@outkept.com](mailto:support@outkept.com) met je organisatienaam en je endpoint-URL.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.