Webhook-API
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 beschreibt die Einrichtung in der App.
Anfrage
Abschnitt betitelt „Anfrage“POST https://<your Pyn host>/api/webhook/<webhookId>Authorization: Bearer <secret>Content-Type: application/jsonIdempotency-Key: <any string> (optional)
{ "subject_id": "E1234", "fields": { "jobTitle": "Account Executive", "startedOnboarding": true, "firstWeekRating": 4 }}webhookIdund das Secret stammen aus dem Seitenpanel Settings des Formulars. Das Secret wird nur einmal angezeigt, wenn es erzeugt wird.subject_idist 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.fieldsenthä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,trueoderfalsefü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
fieldsverschachtelt sind, verhindert, dass Feldnamen mitsubject_idkollidieren.
Antworten
Abschnitt betitelt „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
Abschnitt betitelt „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
Abschnitt betitelt „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_idmitalready-submittedverworfen. 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
Abschnitt betitelt „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; ein Aufrufer, der denselben Fehler wiederholt, aktualisiert eine einzige Benachrichtigung.
Secrets
Abschnitt betitelt „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
Abschnitt betitelt „Verwandte Seiten“- Einen Webhook erstellen für die Schritte in der App.
- Feldtypen in Formularen für die Werte, die jedes Feld annimmt.
- Notices dafür, wo verworfene Payloads auftauchen.