Ganchos web
Reciba notificaciones en tiempo real cuando sucedan cosas. Los webhooks envían solicitudes HTTP POST a su servidor cada vez que se realizan pedidos, los asistentes se registran, se capturan clientes potenciales del stand y más.
¿Qué son los webhooks?
Los webhooks son solicitudes HTTP POST automatizadas enviadas a una URL que usted especifique. En lugar de sondear el API para detectar cambios, su servidor recibe una notificación en el momento en que ocurre un evento. Cada carga útil de webhook incluye el tipo de evento, una marca de tiempo y los datos relevantes.
Creando un punto final
Vaya a Administrador, luego a Crecimiento y luego a Webhooks. Haga clic en Crear punto final. Ingrese un nombre para el punto final (para su referencia), la URL de destino donde se deben enviar las cargas útiles y, opcionalmente, filtre qué tipos de eventos desea recibir. Se genera automáticamente un secreto de firma; lo necesitará para verificar las cargas útiles entrantes.
Tipos de eventos
Los siguientes tipos de eventos están disponibles. Cada tipo corresponde a una acción específica en la plataforma.
| Tipo de evento | Descripción |
|---|---|
| seguimiento.attributed_order | Un visitante rastreado completó un pedido (incluye datos de atribución) |
| pedido.pagado | Un pedido fue pagado exitosamente |
| asistente.checked_in | Un asistente fue registrado en el evento. |
| asistente.conexión_hecha | Dos asistentes conectados al evento |
| stand.lead_captured | Un expositor del stand captó una nueva pista |
| cabina.escanear | Se escaneó una credencial en un stand |
| cabina.conexión_creada | Se realizó una conexión entre un asistente y un expositor |
| stand.order_paid | Se compró un paquete de stand. |
Filtrado de eventos
De forma predeterminada, un nuevo punto final recibe todos los tipos de eventos. Utilice el filtro de eventos para seleccionar solo los tipos que le interesan. Esto reduce el ruido y el procesamiento en su servidor. Puede actualizar los filtros en cualquier momento sin volver a crear el punto final.
Verificación de firma
Cada solicitud de webhook incluye un encabezado de firma por motivos de seguridad. Utilice el secreto de firma del punto final para verificar que la carga útil fue enviada por Kagibag y no ha sido manipulada.
// The signature is included in the request headers
// Verify using HMAC-SHA256 with your endpoint secret
const signature = request.headers['x-webhook-signature'];
const expected = hmac('sha256', endpointSecret, request.body);
const isValid = timingSafeEqual(signature, expected);Entrega y reintentos
Cuando falla una entrega (su servidor devuelve un código de estado que no es 2xx o se agota el tiempo de espera), Kagibag vuelve a intentarlo automáticamente. Los reintentos utilizan un retroceso exponencial: cada intento espera más que el anterior. El sistema realiza hasta seis intentos por defecto. Una vez agotados todos los intentos, la entrega se marca como fallida.
Seguimiento de entregas
Vea el historial de entrega de cada punto final en la sección Webhooks. Cada entrega muestra el tipo de evento, el código de estado HTTP, la cantidad de intentos, las marcas de tiempo y cualquier mensaje de error. Haga clic en una entrega para inspeccionar la carga útil completa de la solicitud, lo que resulta útil para depurar problemas de integración.
Pruebas
Utilice el botón Enviar prueba en cualquier terminal para activar una carga útil de prueba. La prueba utiliza el order.paid tipo de evento con untest: true bandera en los datos. Esto le permite verificar que se pueda acceder a su punto final y procesar las cargas útiles correctamente antes de activarlo.
Solución de problemas
Problemas comunes y cómo resolverlos.
| problema | Solución |
|---|---|
| El punto final devuelve errores 4xx | Verifique que la URL sea correcta y que su servidor esté esperando solicitudes POST en esa ruta. Verifique que su servidor acepte el tipo de contenido JSON. |
| Entregas agotadas | Todos los reintentos fallaron. Verifique los registros del servidor para detectar el error. Solucione el problema y vuelva a habilitar el punto final: los nuevos eventos comenzarán de nuevo. |
| La firma no coincide | Asegúrese de utilizar el secreto de punto final correcto y de verificar el cuerpo de la solicitud sin formato (no una versión analizada). Verifique que su implementación HMAC utilice SHA-256. |
| Punto final deshabilitado | Los puntos finales se desactivan automáticamente después de fallas repetidas. Vuelva a habilitarlo en la configuración de Webhooks después de solucionar el problema subyacente. |