> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks y flows

> Errores al configurar webhooks y al invocar flows de WhatsApp.

Esta página cubre [Webhooks](/client/webhooks/index) y [Flows](/client/flows/create). Además de lo que se lista acá, cualquiera de estos endpoints puede devolver los [errores comunes](/client/base/errors/common). Los que tienen un ID en la ruta también responden `404 record_not_found` si el ID no es un UUID, y `404 environment_key_mismatch` si el recurso es del otro ambiente.

**Endpoints:** [Listar webhooks](#listar-webhooks) · [Crear](#crear-un-webhook) · [Detalle](#detalle-y-eliminar-un-webhook) · [Actualizar](#actualizar-un-webhook) · [Invocar un flow](#invocar-un-flow)

## Webhooks

### Listar webhooks

`GET /webhooks` · [Referencia](/client/webhooks/list)

Este endpoint no tiene errores propios. Solo aplican los [errores comunes](/client/base/errors/common).

El listado trae los webhooks de los dos ambientes. Para abrir, editar o eliminar uno, usa la llave del ambiente en que lo creaste: con la otra recibes `404 environment_key_mismatch`.

### Crear un webhook

`POST /webhooks` · [Referencia](/client/webhooks/create)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10001`<br />`validation_error` | 422 | El campo nombre es obligatorio. | Falta `name`, `url` o `events`, `events` está vacío, o un evento no existe («El events.0 seleccionado es inválido.»). | Envía `name`, una `url` válida y al menos un evento del catálogo. | Sí, tras corregir |
| `10001`<br />`validation_error` | 422 | La URL del webhook debe usar https para recibir eventos en producción. | Con la llave de producción, `url` no es `https` o no es una URL válida. | Usa una URL `https` pública. | Sí, tras corregir |

### Detalle y eliminar un webhook

`GET /webhooks/{id}` · [Referencia](/client/webhooks/detail)<br />
`DELETE /webhooks/{id}` · [Referencia](/client/webhooks/delete)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, Webhook no existe | El webhook no existe, ya se eliminó o es de otra empresa. | Revisa el `id` con [listar webhooks](/client/webhooks/list). | No |

### Actualizar un webhook

`PUT /webhooks/{id}` · [Referencia](/client/webhooks/update)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, Webhook no existe | El webhook no existe, se eliminó o es de otra empresa. | Revisa el `id`. | No |
| `10001`<br />`validation_error` | 422 | El campo events debe ser un conjunto. | Un campo enviado no es válido: `events` vacío o con un evento que no existe, o `name` o `url` con formato inválido. | Revisa `errors` y corrige el cuerpo. | Sí, tras corregir |
| `10001`<br />`validation_error` | 422 | La URL del webhook debe usar https para recibir eventos en producción. | Con la llave de producción, `url` no es `https` o no es una URL válida. | Usa una URL `https` pública. | Sí, tras corregir |

## Invocar un flow

`POST /flows` · [Referencia](/client/flows/create) · [Pago de facturas](/client/flows/bill-payment)

Este endpoint no exige `x-idempotency`.

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10001`<br />`validation_error` | 422 | El numero de teléfono no es valido, debe ser un numero en formato E.164 | Falta `phone` o no es válido; `flow` no es uno de la lista; falta `params.reference` en `bill-payment`; o `params.amount` no es numérico o supera 1.000.000. | Revisa `errors` y corrige el cuerpo. | Sí, tras corregir |
| `10001`<br />`validation_error` | 422 | El canal no existe o no pertenece a la empresa. | `params.channel_id` no es un canal de WhatsApp que tu empresa pueda usar. | Usa uno de tus canales o no lo envíes. | Sí, tras corregir |
| `10001`<br />`validation_error` | 422 | El monto mínimo es COP \$1.000 | `params.amount` está por debajo del mínimo de la moneda. | Envía un monto igual o mayor al mínimo. | Sí, tras corregir |
| `28006`<br />`flow_not_found` | 404 | No se encontró el flujo a invocar | No enviaste `flow`. Es opcional en la validación, así que su ausencia llega como `28006` y no como `10001`. | Envía `flow`: `demo`, `create_bill`, `payment_methods`, `bill-payment` o `payment`. | Sí, tras corregir |
| `28008`<br />`flow_recent_send` | 419 | El flujo fue enviado al mismo número hace menos de 1 minuto | Ya invocaste el mismo flow al mismo teléfono hace menos de 60 segundos. | Espera un minuto antes de volver a invocarlo. | Sí, tras esperar |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, BillService no existe | Con `flow: payment`, tu empresa no tiene un convenio de facturas configurado. | Escribe a soporte para configurarlo. | No |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado | Con `flow: payment` sin `params.amount`, no se encontró una factura para `params.reference`. | Revisa la referencia, o envía `params.reference` y `params.amount` para cobrar sin consultar. | Sí, tras corregir |

Un `200` significa que el flow se aceptó, no que el mensaje de WhatsApp llegó.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.