Ir al contenido
PynPyn

API del webhook

Un webhook pertenece a un formulario. Otro sistema le envía un cuerpo JSON con un secreto bearer; Pyn acepta la carga y después, por separado, la convierte en un envío del formulario para el empleado que nombra, registrando el resultado en el webhook. Crea un webhook cubre la configuración en la 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 y el secreto salen del panel lateral Settings del formulario. El secreto se muestra una sola vez, al generarlo.
  • subject_id es el id del empleado en el sistema de origen elegido en Subject en el formulario (por ejemplo, un BambooHR Employee ID). Pyn busca al empleado que tiene ese id en ese sistema; el mismo id en otro sistema no coincide.
  • fields contiene una entrada por campo del formulario, nombrada por el alias del campo (su etiqueta en camel case) o por su clave. Cada clave debe nombrar un campo del formulario, y cada valor debe ser uno que el campo pueda contener: una cadena de hasta 2.048 caracteres para Text, true o false para Checkbox, un entero del 1 al 5 para Likert Scale, el id de empleado de Pyn (36 caracteres, no un id del HRIS) para Buddy y Mentor. Los campos Content no admiten valor.
  • El cuerpo debe ser un objeto JSON. Anidar los valores bajo fields evita que los nombres de campo choquen con subject_id.
Estado Significado
202 Aceptada. La carga se ha recibido y se procesará; esto no significa que el envío haya tenido éxito. Lee el log.
404 Rechazada: el id está mal formado o es desconocido, el webhook está archivado o el secreto bearer no coincide. Los casos no se distinguen, así que el endpoint no se puede sondear.

Una petición que llega al endpoint con un cuerpo que no es JSON, o durante un fallo del lado de Pyn, recibe el 4xx o 5xx habitual; un 5xx se puede reintentar.

Si envías una cabecera Idempotency-Key, una repetición de la misma clave al mismo webhook se confirma con 202 y no se procesa más. La misma clave enviada a otro webhook es una entrega distinta. Sin la cabecera, cada petición se procesa. El eventId del log es la referencia para rastrear una entrega.

  • Un webhook envía como mucho una vez por empleado. Una vez completado el envío de un sujeto, las cargas posteriores con el mismo subject_id se descartan con already-submitted. Un formulario que necesita respuestas repetidas de una misma persona no puede usar un webhook para ellas.
  • Una carga se acepta entera o no se acepta: un campo obligatorio ausente o un valor del tipo equivocado descarta toda la carga en lugar de registrar un envío parcial.
  • Un formulario sin Subject configurado no acepta nada (no-subject).
  • Un envío aceptado se comporta como cualquier otro: aparece en el panel lateral Activity del formulario y en la exportación, escribe los valores de Buddy o Mentor en el empleado e inicia cualquier automation con un trigger Form Submission sobre el formulario.

Cada carga deja una entrada en el log del webhook (el panel lateral Settings del formulario, con una exportación CSV de todo el log).

Código Resultado Significado
submitted Procesada Se registró un envío para el identificador.
no-subject Descartada El formulario no tiene configurado un sujeto para el webhook.
invalid-payload Descartada El cuerpo no se pudo interpretar como { subject_id, fields }; el mensaje nombra el campo y el motivo.
unknown-subject Descartada Ningún empleado tiene ese identificador en el sistema de origen elegido.
already-submitted Descartada Este webhook ya ha enviado para ese identificador.
ambiguous-fields Descartada Un nombre coincidió con más de un campo, o un campo se nombró dos veces (por clave y por alias).
missing-fields Descartada No se proporcionó un campo obligatorio.
invalid-fields Descartada Una clave no nombra ningún campo del formulario, o un valor no es del tipo que admite su campo.

Cada carga descartada también genera un aviso en Notices; un emisor que repite el mismo error actualiza un único aviso.

Acción Efecto
Create Secret Genera el secreto de un webhook que no tiene ninguno. Un webhook sin secreto no acepta nada.
Replace Secret Genera un secreto nuevo; el anterior deja de funcionar de inmediato.

Los secretos se muestran una sola vez y no se pueden volver a consultar. Ambas acciones requieren ser Admin.