Probar Webhooks
Probar Webhooks
Desde el panel puedes enviar un evento de prueba a cualquiera de tus webhooks y revisar después qué pasó con esa entrega: el código de respuesta de tu servidor, el cuerpo que devolvió y, si falló, el error exacto.
El evento de prueba viaja por el mismo camino que un evento real: mismos headers (incluida la firma X-Webhook-Signature), mismo tiempo límite y mismo registro de entregas. Lo que ves en la prueba es lo que va a pasar en producción.
Esta función se está habilitando organización por organización. Si todavía no ves la sección de webhooks con el botón de prueba en tu panel, tu organización aún no la tiene activa.
Todo esto funciona igual dentro del sandbox, contra datos que no existen y cobros que no movieron dinero — que suele ser donde conviene probar un handler antes de apuntarlo a producción. Ver Probar webhooks en el sandbox.
Enviar un evento de prueba
- Entra al panel y ve a Desarrolladores → Webhooks
- Ubica el webhook que quieres probar
- Haz clic en Enviar evento de prueba
- Elige el tipo de evento
- Confirma el envío
Venflow arma un payload de ejemplo del tipo elegido y lo envía a la URL configurada en ese webhook.
Qué contiene el payload de prueba
Son datos claramente ficticios, con la misma forma que un evento real: identificadores como inv_ejemplo_00000000, montos redondos y textos como Banco de Ejemplo. Nunca se envían datos de tus clientes reales en una prueba.
La estructura de cada tipo de evento está en la referencia de eventos.
Diferencias con un evento real
| Aspecto | Evento real | Evento de prueba |
|---|---|---|
| Headers y firma | Iguales | Iguales |
| Tiempo límite | 5 segundos | 5 segundos |
| Reintentos | Hasta 3 intentos, cada 5 minutos | Un solo intento |
| Correo de aviso al fallar | Sí, al agotar los intentos | No |
| Historial de entregas | Sí | Sí, marcado como prueba |
Un evento de prueba no se reintenta a propósito: estás depurando tu endpoint y no tiene sentido esperar 10 minutos por dos reintentos de algo que ya sabes que falló. Corrige y vuelve a disparar.
Tipos de evento disponibles
Puedes disparar cualquiera de estos:
| Evento | Descripción |
|---|---|
USER_CREATE_EVENT | Nuevo cliente creado |
SUBSCRIPTION_CREATE_EVENT | Suscripción creada |
SUBSCRIPTION_UPDATED_EVENT | Suscripción con cambio de estado |
SUBSCRIPTION_CANCELLED_EVENT | Suscripción cancelada |
INVOICE_CREATE_EVENT | Factura generada |
INVOICE_UPDATE_EVENT | Estado de factura actualizado |
PAYMENT_SUCCESS_EVENT | Pago exitoso |
PAYMENT_FAILED_EVENT | Pago fallido |
PAYMENT_REMINDER_PRE_EVENT | Recordatorio antes del cobro |
PAYMENT_REMINDER_POST_EVENT | Recordatorio tras un cobro fallido |
Solo puedes disparar un evento al que ese webhook esté suscrito. Si el webhook tiene events: ["PAYMENT_SUCCESS_EVENT"] y pides un INVOICE_CREATE_EVENT, la prueba se rechaza en lugar de enviarse: así la prueba nunca te hace creer que recibirás un evento que en producción no va a llegar. Si el webhook no tiene eventos configurados (recibe todos), cualquier tipo funciona.
Historial de entregas
La misma sección muestra los intentos de entrega recientes de tus webhooks, incluidos los fallidos. Cada fila trae:
| Columna | Detalle |
|---|---|
| Evento | Tipo de evento entregado |
| Estado | Éxito o fallo del intento |
| Código HTTP | Lo que respondió tu servidor, o vacío si nunca hubo respuesta (timeout, DNS, conexión rechazada) |
| Respuesta | El cuerpo devuelto por tu servidor, recortado; en un fallo de red, el texto del error. Se ve al desplegar la fila con la flecha del final |
| Intento | Número de intento dentro de la política de reintentos (1, 2 o 3) |
| Prueba | Marca las entregas disparadas con Enviar evento de prueba |
| Fecha | Momento del intento |
Las entregas se listan de la más reciente a la más antigua y se conservan 30 días.
Leer un fallo
- Código
4xx: tu servidor recibió el evento y lo rechazó. Revisa la validación de la firma y el formato que espera tu handler. - Código
5xx: tu código explotó procesando el evento. El cuerpo de la respuesta suele traer la pista. - Sin código HTTP: la solicitud nunca llegó a completarse. Causas típicas: la URL no resuelve, el certificado TLS no es válido, el puerto está cerrado, o tu servidor tardó más de 5 segundos en responder.
- Tres intentos fallidos seguidos (solo en eventos reales): Venflow envía un correo de aviso a la organización.
Probar sin tener un endpoint listo
Si todavía no tienes servidor, webhook.site te da una URL temporal que acepta cualquier POST y te muestra lo que recibió, headers incluidos:
- Entra a webhook.site y copia la URL única que genera
- Crea un webhook en Venflow con esa URL
- Dispara un evento de prueba
- Revisa en webhook.site el cuerpo y los headers, incluido
X-Webhook-Signature
Es útil para confirmar que el evento sale y ver su forma exacta, pero no reemplaza probar contra tu propio endpoint: la verificación de la firma solo la puedes comprobar en tu código. Ver Verificar la firma.
Probar en local
Tu máquina de desarrollo no es alcanzable desde internet, así que Venflow no puede entregarle nada directamente. Usa un túnel que exponga tu puerto local con una URL pública (por ejemplo ngrok o cloudflared), y registra esa URL pública en el webhook. Recuerda que el túnel cambia de URL cada vez que lo reinicias, salvo que uses un dominio fijo.