Webhooks y flows

Esta página cubre Webhooks y Flows. Además de lo que se lista acá, cualquiera de estos endpoints puede devolver los errores comunes. 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 · Crear · Detalle · Actualizar · Invocar un flow

Webhooks

Listar webhooks

GET /webhooks · Referencia Este endpoint no tiene errores propios. Solo aplican los errores comunes. 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

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10001` `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` `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
DELETE /webhooks/{id} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `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.	No

Actualizar un webhook

PUT /webhooks/{id} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `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` `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` `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 · Pago de facturas Este endpoint no exige x-idempotency.

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10001` `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` `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` `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` `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` `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` `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` `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ó.

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

Webhooks

Listar webhooks

Crear un webhook

Detalle y eliminar un webhook

Actualizar un webhook

Invocar un flow

​Webhooks

​Listar webhooks

​Crear un webhook

​Detalle y eliminar un webhook

​Actualizar un webhook

​Invocar un flow

Webhooks

Listar webhooks

Crear un webhook

Detalle y eliminar un webhook

Actualizar un webhook

Invocar un flow