Zum Inhalt springen
PynPyn

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.

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.
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.

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.

  • 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.

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.

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.