---
title: "Webhook-API"
description: "Der eingehende Webhook eines Formulars: Endpunkt, Bearer-Secret, JSON-Body mit subject_id und fields, Idempotenzschlüssel, die zwei Antworten, die Regel „einmal pro Person“ und jeder Code, den das Protokoll aufzeichnen kann."
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
---

Ein Webhook gehört zu genau einem Formular. Ein anderes System postet einen JSON-Body mit einem Bearer-Secret an ihn; Pyn nimmt die Payload an und macht daraus in einem separaten Schritt eine Einsendung auf dem Formular für die genannte Person, mit dem Ergebnis im Protokoll des Webhooks. [Einen Webhook erstellen](https://support.pyn.ai/de/flows/forms/create-a-webhook/) beschreibt die Einrichtung in der App.

## Anfrage

```
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` und das Secret stammen aus dem Seitenpanel **Settings** des Formulars. Das Secret wird nur einmal angezeigt, wenn es erzeugt wird.
- `subject_id` ist die ID der Person im Quellsystem, das unter **Subject** auf dem Formular gewählt ist (zum Beispiel eine BambooHR Employee ID). Pyn sucht die Person, die diese ID aus diesem System hat; dieselbe ID aus einem anderen System passt nicht.
- `fields` enthält einen Eintrag pro Formularfeld, benannt nach dem Alias des Feldes (seine Beschriftung in camelCase) oder seinem Schlüssel. Jeder Schlüssel muss ein Feld auf dem Formular benennen, und jeder Wert muss einer sein, den das Feld aufnehmen kann: ein String mit bis zu 2.048 Zeichen für **Text**, `true` oder `false` für **Checkbox**, eine ganze Zahl von 1 bis 5 für **Likert Scale**, die Pyn-Mitarbeitenden-ID (36 Zeichen, keine HRIS-ID) für **Buddy** und **Mentor**. **Content**-Felder nehmen keinen Wert an.
- Der Body muss ein JSON-Objekt sein. Dass die Werte unter `fields` verschachtelt sind, verhindert, dass Feldnamen mit `subject_id` kollidieren.

## Antworten

| Status | Bedeutung |
| --- | --- |
| `202` | Angenommen. Die Payload wurde entgegengenommen und wird verarbeitet; das heißt nicht, dass die Einsendung gelungen ist. Lies das Protokoll. |
| `404` | Abgelehnt: Die ID ist fehlerhaft oder unbekannt, der Webhook ist archiviert oder das Bearer-Secret passt nicht. Die Fälle werden nicht unterschieden, damit sich der Endpunkt nicht ausspähen lässt. |

Eine Anfrage, die den Endpunkt mit einem Body erreicht, der kein JSON ist, oder während einer Störung auf Pyns Seite, bekommt den üblichen `4xx`- oder `5xx`-Status; ein `5xx` kann wiederholt werden.

## Idempotenz

Sende einen Header `Idempotency-Key`, und eine Wiederholung desselben Schlüssels an denselben Webhook wird mit `202` bestätigt und nicht weiter verarbeitet. Derselbe Schlüssel an einen anderen Webhook ist eine eigene Zustellung. Ohne den Header wird jeder Post verarbeitet. Die `eventId` im Protokoll ist der Anker, um eine Zustellung nachzuverfolgen.

## Verarbeitungsregeln

- Ein Webhook sendet pro Person höchstens einmal ein. Sobald die Einsendung für ein Subject abgeschlossen ist, werden spätere Payloads für dieselbe `subject_id` mit `already-submitted` verworfen. Ein Formular, das wiederholte Antworten von einer Person braucht, kann dafür keinen Webhook nutzen.
- Eine Payload wird ganz oder gar nicht übernommen: Ein fehlendes Pflichtfeld oder ein Wert vom falschen Typ verwirft die ganze Payload, statt eine Teileinsendung aufzuzeichnen.
- Ein Formular ohne gesetztes **Subject** nimmt nichts an (`no-subject`).
- Eine angenommene Einsendung verhält sich wie jede andere: Sie erscheint im Seitenpanel **Activity** des Formulars und im Export, schreibt Buddy- oder Mentor-Werte in den Datensatz der Person und startet jede Automation mit einem Trigger **Form Submission** auf dem Formular.

## Protokollcodes

Jede Payload hinterlässt einen Eintrag im Protokoll des Webhooks (im Seitenpanel **Settings** des Formulars, mit einem CSV-Export des gesamten Protokolls).

| Code | Ergebnis | Bedeutung |
| --- | --- | --- |
| `submitted` | Verarbeitet | Eine Einsendung für die Kennung wurde aufgezeichnet. |
| `no-subject` | Verworfen | Das Formular hat kein Webhook-Subject konfiguriert. |
| `invalid-payload` | Verworfen | Der Body ließ sich nicht als `{ subject_id, fields }` lesen; die Meldung nennt Feld und Grund. |
| `unknown-subject` | Verworfen | Keine Person hat diese Kennung im gewählten Quellsystem. |
| `already-submitted` | Verworfen | Dieser Webhook hat für diese Kennung bereits eingesendet. |
| `ambiguous-fields` | Verworfen | Ein Name passte auf mehr als ein Feld, oder ein Feld wurde zweimal benannt (per Schlüssel und per Alias). |
| `missing-fields` | Verworfen | Ein Pflichtfeld wurde nicht mitgeliefert. |
| `invalid-fields` | Verworfen | Ein Schlüssel benennt kein Feld auf dem Formular, oder ein Wert hat den falschen Typ für sein Feld. |

Jede verworfene Payload erzeugt außerdem eine Benachrichtigung in [Notices](https://support.pyn.ai/de/notices/); ein Aufrufer, der denselben Fehler wiederholt, aktualisiert eine einzige Benachrichtigung.

## Secrets

| Aktion | Wirkung |
| --- | --- |
| **Create Secret** | Erzeugt das Secret für einen Webhook, der keins hat. Ein Webhook ohne Secret nimmt nichts an. |
| **Replace Secret** | Erzeugt ein neues Secret; das alte funktioniert sofort nicht mehr. |

Secrets werden einmal angezeigt und lassen sich nicht erneut auslesen. Beide Aktionen erfordern einen Admin.

## Verwandte Seiten

- [Einen Webhook erstellen](https://support.pyn.ai/de/flows/forms/create-a-webhook/) für die Schritte in der App.
- [Feldtypen in Formularen](https://support.pyn.ai/de/flows/forms/reference-form-field-types/) für die Werte, die jedes Feld annimmt.
- [Notices](https://support.pyn.ai/de/notices/) dafür, wo verworfene Payloads auftauchen.
