Webhook-API
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 beschrijft het instellen in de app.
Request
Section titled “Request”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 }}webhookIden het secret komen uit het Settings-zijpaneel van het formulier. Het secret wordt één keer getoond, bij het aanmaken.subject_idis 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.fieldsbevat éé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,trueoffalsevoor 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
fieldste nesten botsen veldnamen niet metsubject_id.
Antwoorden
Section titled “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
Section titled “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
Section titled “Verwerkingsregels”- Een webhook dient hoogstens één keer per medewerker in. Zodra de inzending van een subject compleet is, worden latere payloads voor dezelfde
subject_idafgewezen metalready-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
Section titled “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; een aanroeper die dezelfde fout herhaalt, werkt één notice bij.
Secrets
Section titled “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
Section titled “Gerelateerd”- Een webhook maken voor de stappen in de app.
- Veldtypen in formulieren voor de waarden die elk veld accepteert.
- Notices voor waar afgewezen payloads zichtbaar worden.