---
title: "API del webhook"
description: "El webhook de entrada de un formulario: endpoint, secreto bearer, cuerpo JSON con subject_id y fields, clave de idempotencia, las dos respuestas, la regla de un envío por empleado y todos los códigos que puede registrar el log."
sidebar:
  order: 3
area: flows
feature: forms
appPath: /flows/home
lastVerified: 2026-11-15
version: "2026-10-23"
audience: admin
related:
  - flows/forms/create-a-webhook
  - flows/forms/reference-form-field-types
  - notices
intercom:
  - id: "16858360"
    title: Create a Webhook (Pyn 2)
    url: https://intercom.help/pyn/en/articles/16858360-create-a-webhook-pyn-2
    note: draws on
translation:
  source: flows/forms/reference-webhook-api.mdx
  sourceSha: 2c607d39875f121d7d36587eff499f6edebd6ed7
---

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](https://support.pyn.ai/es/flows/forms/create-a-webhook/) cubre la configuración en la app.

## Petición

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

## Respuestas

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

## Idempotencia

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.

## Reglas de procesamiento

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

## Códigos del log

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](https://support.pyn.ai/es/notices/); un emisor que repite el mismo error actualiza un único aviso.

## Secretos

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

## Relacionado

- [Crea un webhook](https://support.pyn.ai/es/flows/forms/create-a-webhook/) para los pasos en la app.
- [Tipos de campo de formulario](https://support.pyn.ai/es/flows/forms/reference-form-field-types/) para los valores que acepta cada campo.
- [Notices](https://support.pyn.ai/es/notices/) para ver dónde aparecen las cargas descartadas.
