Ga naar inhoud
PynPyn

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.

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

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.

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

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.

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.