Cómo monitorear las entregas de webhooks

​

Descripción general

Cuando Alvys envía un evento a su endpoint de webhook, el resultado queda registrado. El panel Delivery Logs en la página de detalle de un webhook muestra cada intento con su resultado, para que pueda distinguir entre “Alvys nunca lo envió” y “su endpoint lo rechazó” sin pedirle a nadie que revise un registro del servidor. Un indicador de salud en la misma página señala un endpoint que ha empezado a fallar, lo que suele ser la primera señal de que algo cambió del lado receptor: un certificado vencido, una URL que se movió, un despliegue que rompió un handler. También conocido como: registros de webhook, historial de entregas, fallas de webhook, solución de problemas de webhooks.

​

Antes de empezar

• Su cuenta necesita la Public API de Alvys habilitada, y usted necesita acceso a la sección Webhooks en Settings.
• Debe existir al menos una suscripción de webhook. Los registros se guardan por suscripción, así que un webhook creado hoy todavía no tiene historial.
• Los registros de entrega se conservan según la política estándar de retención de datos de Alvys. Exporte lo que necesite conservar como pista de auditoría.

​

Pasos

1. Abra sus suscripciones de webhook.
   • Vaya a Settings → API → Webhooks.
   • La página enumera las suscripciones de webhook configuradas en su cuenta.
2. Abra el webhook que quiera inspeccionar.
   • Haga clic en el webhook para abrir su página de detalle.
   • El panel Delivery Logs se abre junto a la configuración del webhook.
3. Lee el historial de entregas. Cada entrada del panel muestra:
   • Event type — qué evento intentó entregar Alvys.
   • Status — una etiqueta que dice Success, Failed o Skipped.
   • Timestamp — cuándo se realizó el intento.
   • Error message — qué devolvió su endpoint; se muestra solo cuando el intento falló.
   La lista carga una página de entradas a la vez, así que desplácese o avance de página para ver intentos más antiguos.
4. Reduce la lista a lo que está investigando.
   • Use el filtro de estado para mostrar All, Success, Skipped o Failed.
   • Filtrar por Failed es la forma más rápida de ver si las fallas comparten un tipo de evento o una misma ventana de tiempo.
5. Exporte el historial si lo necesita fuera de Alvys.
   • Use Export .CSV o Export .JSON en la parte inferior del panel de registros.

​

Resultado

Puede ver el resultado de cada intento de entrega de la suscripción, saber si una falla provino de Alvys o de su endpoint, y entregarle a un desarrollador un registro exportado en lugar de una descripción.

​

Entender los estados

Una serie de entradas Skipped casi siempre significa que la suscripción estaba desactivada, incluso de forma automática tras fallas repetidas. Verifique si el webhook sigue habilitado antes de investigar el endpoint.

​

Salud del webhook y desactivación automática

La página de detalle del webhook muestra un indicador de salud para que detecte de un vistazo un endpoint que se está degradando, en lugar de tener que leer el registro. Si un webhook sigue fallando, Alvys lo deshabilita automáticamente y envía un correo a sus Partner Admins. Una vez que eso ocurre, la suscripción deja de intentar entregas y los eventos posteriores se registran como Skipped. Corrija el endpoint y vuelva a habilitar la suscripción.

​

Solución de problemas

​

Todas las entregas recientes muestran Failed

1. Lee el mensaje de error de una de las entradas fallidas: es lo que devolvió su endpoint, así que normalmente nombra el problema directamente.
2. Confirme que la URL del endpoint en el webhook sigue siendo correcta y accesible desde fuera de su red.
3. Verifique si todas las fallas comienzan en la misma marca de tiempo. Un corte limpio suele apuntar a un cambio del lado receptor más que a Alvys.

​

Las entregas muestran Skipped y no llega nada

1. Verifique si la suscripción está habilitada. Un webhook pausado o deshabilitado automáticamente registra Skipped en lugar de intentar la entrega.
2. Consulte con sus Partner Admins si recibieron un correo sobre la desactivación del webhook tras fallas repetidas.
3. Vuelva a habilitar la suscripción una vez corregido el endpoint.

​

El registro está vacío

1. Confirme que la suscripción ha existido el tiempo suficiente para que haya ocurrido un evento coincidente.
2. Confirme que el webhook está suscrito a los eventos que espera ver. Sin un evento coincidente no hay intento de entrega y, por tanto, no hay entrada en el registro.

​

A una exportación le faltan filas que veo en pantalla

Aplique sus filtros y avance de página para cargar primero las entradas que quiera. La exportación solo incluye lo que abarcan sus filtros actuales y las páginas cargadas.

​

Preguntas frecuentes

P: ¿Puedo reintentar una entrega fallida desde esta pantalla? R: Por ahora no. Exporte las entradas fallidas y vuelva a disparar los eventos desde su propio sistema. P: ¿Una entrada Skipped significa que la entrega falló? R: No. Skipped significa que Alvys no intentó la entrega en absoluto, porque la suscripción estaba deshabilitada o pausada cuando se generó el evento. P: ¿Me avisarán cuando un webhook deje de funcionar? R: Sí. Se envía un correo automático a los Partner Admins cuando un webhook se deshabilita tras fallas repetidas. El indicador de salud en la página de detalle del webhook también refleja su estado actual. P: ¿Hasta qué punto atrás llegan los registros? R: Los registros de entrega siguen la política estándar de retención de datos de Alvys. Exporte los registros que necesite conservar más allá de ese plazo. P: ¿La exportación incluye todo el historial? R: No: solo las entradas que coinciden con sus filtros actuales y las páginas que ha cargado.

​

Profundiza

• Alvys API