---
title: "Webhook-API"
description: "De inkomende webhook op een formulier: endpoint, bearer-secret, JSON-body met subject_id en fields, idempotency-key, de twee antwoorden, de regel van één inzending per medewerker en elke code die het log kan vastleggen."
sidebar:
  order: 3
area: flows
feature: forms
appPath: /flows/home
lastVerified: 2026-11-15
version: "2026-10-23"
audience: admin
related:
  - flows/forms/create-a-webhook
  - flows/forms/reference-form-field-types
  - notices
intercom:
  - id: "16858360"
    title: Create a Webhook (Pyn 2)
    url: https://intercom.help/pyn/en/articles/16858360-create-a-webhook-pyn-2
    note: draws on
translation:
  source: flows/forms/reference-webhook-api.mdx
  sourceSha: 2c607d39875f121d7d36587eff499f6edebd6ed7
---

Een webhook hoort bij één formulier. Een ander systeem post er een JSON-body naartoe met een bearer-secret; Pyn accepteert de payload en zet die daarna apart om in een inzending op het formulier voor de medewerker die erin wordt genoemd, en legt de uitkomst vast in het log van de webhook. [Een webhook maken](https://support.pyn.ai/nl/flows/forms/create-a-webhook/) beschrijft het instellen in de app.

## Request

```
POST https://<your Pyn host>/api/webhook/<webhookId>
Authorization: Bearer <secret>
Content-Type: application/json
Idempotency-Key: <any string>      (optional)

{
  "subject_id": "E1234",
  "fields": {
    "jobTitle": "Account Executive",
    "startedOnboarding": true,
    "firstWeekRating": 4
  }
}
```

- `webhookId` en het secret komen uit het **Settings**-zijpaneel van het formulier. Het secret wordt één keer getoond, bij het aanmaken.
- `subject_id` is het id van de medewerker in het bronsysteem dat onder **Subject** op het formulier is gekozen (bijvoorbeeld een BambooHR Employee ID). Pyn zoekt de medewerker die dat id uit dat systeem heeft; hetzelfde id uit een ander systeem matcht niet.
- `fields` bevat één item per formulierveld, benoemd bij de alias van het veld (zijn label in camelCase) of bij zijn key. Elke key moet een veld op het formulier benoemen, en elke waarde moet er een zijn die het veld kan bevatten: een tekst van maximaal 2.048 tekens voor **Text**, `true` of `false` voor **Checkbox**, een geheel getal van 1 tot en met 5 voor **Likert Scale**, het Pyn-medewerkers-id (36 tekens, geen HRIS-id) voor **Buddy** en **Mentor**. **Content**-velden nemen geen waarde aan.
- De body moet een JSON-object zijn. Door waarden onder `fields` te nesten botsen veldnamen niet met `subject_id`.

## Antwoorden

| Status | Betekenis |
| --- | --- |
| `202` | Geaccepteerd. De payload is aangenomen en wordt verwerkt; dit betekent niet dat de inzending is gelukt. Lees het log. |
| `404` | Geweigerd: het id is ongeldig of onbekend, de webhook is gearchiveerd, of het bearer-secret klopt niet. De gevallen worden niet onderscheiden, zodat het endpoint niet kan worden afgetast. |

Een request dat het endpoint bereikt met een body die geen JSON is, of tijdens een storing aan de kant van Pyn, krijgt de gebruikelijke `4xx` of `5xx` terug; een `5xx` kan opnieuw worden geprobeerd.

## Idempotentie

Stuur een `Idempotency-Key`-header mee en een herhaling van dezelfde key naar dezelfde webhook wordt bevestigd met `202` en niet verder verwerkt. Dezelfde key naar een andere webhook is een aparte levering. Zonder de header wordt elke post verwerkt. Het `eventId` in het log is het handvat om een levering te traceren.

## Verwerkingsregels

- Een webhook dient hoogstens één keer per medewerker in. Zodra de inzending van een subject compleet is, worden latere payloads voor dezelfde `subject_id` afgewezen met `already-submitted`. Een formulier dat herhaalde antwoorden van één persoon nodig heeft kan daarvoor geen webhook gebruiken.
- Een payload wordt in zijn geheel aangenomen of helemaal niet: een ontbrekend verplicht veld of een waarde van het verkeerde type wijst de hele payload af in plaats van een gedeeltelijke inzending vast te leggen.
- Een formulier zonder ingesteld **Subject** accepteert niets (`no-subject`).
- Een geaccepteerde inzending gedraagt zich als elke andere: ze verschijnt in het **Activity**-zijpaneel en de export van het formulier, schrijft Buddy- of Mentor-waarden naar de medewerker en start elke automation met een **Form Submission**-trigger op het formulier.

## Logcodes

Elke payload laat één regel achter in het log van de webhook (het **Settings**-zijpaneel van het formulier, met een CSV-export van het hele log).

| Code | Uitkomst | Betekenis |
| --- | --- | --- |
| `submitted` | Verwerkt | Een inzending vastgelegd voor de identifier. |
| `no-subject` | Afgewezen | Het formulier heeft geen webhook-subject ingesteld. |
| `invalid-payload` | Afgewezen | De body kon niet worden gelezen als `{ subject_id, fields }`; het bericht noemt het veld en de reden. |
| `unknown-subject` | Afgewezen | Geen medewerker heeft die identifier in het gekozen bronsysteem. |
| `already-submitted` | Afgewezen | Deze webhook heeft al ingediend voor die identifier. |
| `ambiguous-fields` | Afgewezen | Een naam matchte meer dan één veld, of een veld werd twee keer benoemd (bij key en bij alias). |
| `missing-fields` | Afgewezen | Een verplicht veld is niet meegegeven. |
| `invalid-fields` | Afgewezen | Een key benoemt geen veld op het formulier, of een waarde heeft het verkeerde type voor zijn veld. |

Elke afgewezen payload maakt ook een notice aan in [Notices](https://support.pyn.ai/nl/notices/); een aanroeper die dezelfde fout herhaalt, werkt één notice bij.

## Secrets

| Actie | Effect |
| --- | --- |
| **Create Secret** | Maakt het secret aan voor een webhook die er geen heeft. Een webhook zonder secret accepteert niets. |
| **Replace Secret** | Maakt een nieuw secret aan; het oude werkt per direct niet meer. |

Secrets worden één keer getoond en kunnen niet worden teruggelezen. Voor beide acties is een Admin nodig.

## Gerelateerd

- [Een webhook maken](https://support.pyn.ai/nl/flows/forms/create-a-webhook/) voor de stappen in de app.
- [Veldtypen in formulieren](https://support.pyn.ai/nl/flows/forms/reference-form-field-types/) voor de waarden die elk veld accepteert.
- [Notices](https://support.pyn.ai/nl/notices/) voor waar afgewezen payloads zichtbaar worden.
