Webhooks. Eventos en tiempo real, entregados con fiabilidad.

Lea el cuerpo bruto de la solicitud como bytes (antes de cualquier procesamiento JSON), calcule el HMAC-SHA256 sobre los bytes brutos utilizando el secreto compartido de su punto final, codifique el resultado en base16 (hexadecimal) y compárelo con el valor del encabezado X-Elido-Signature tras quitar el prefijo 'sha256='. Utilice una función de comparación de tiempo constante (por ejemplo, hmac.compare_digest en Python, crypto.timingSafeEqual en Node.js) para evitar ataques de tiempo. Nunca compare la firma con un operador de igualdad de cadenas estándar. Encontrará ejemplos de código para Node.js, Python y Go en /docs/guides/webhooks#verification.

Devuelva HTTP 200 (o cualquier código de estado 2xx) en un plazo de 30 segundos. El cuerpo de la respuesta se ignora; puede devolver un cuerpo vacío o { ok: true }. Si su procesamiento tarda más de 30 segundos, devuelva 200 inmediatamente y procese el evento de forma asíncrona (añádalo a una cola interna, devuelva 200 y procéselo fuera de la ruta de la solicitud). Devolver 4xx se trata igual que 5xx a efectos de reintento: ambos activan un reintento. Devuelva 200 incluso si el evento no es relevante para su integración (por ejemplo, un evento link.created que no necesita) para evitar reintentos innecesarios.

Cada carga útil de webhook incluye un campo event_id (UUID). Utilice este campo como clave de idempotencia en su receptor: si recibe el mismo event_id dos veces (debido a un reintento tras un fallo parcial), procéselo solo una vez. Almacene los ID de los eventos recibidos en una tabla de deduplicación con un TTL de al menos 72 horas (la ventana de reintento). La carga útil del reintento es idéntica a la original -mismo event_id, mismo cuerpo-, por lo que una simple comprobación de '¿ya he visto este event_id?' es suficiente.

Los puntos finales se pausan automáticamente tras 30 fallos de entrega consecutivos (no 2xx o tiempo de espera agotado). Esto evita que Elido sature un punto final defectuoso indefinidamente. Corrija el problema subyacente (normalmente: la URL del punto final cambió, el servidor está caído o se supera el tiempo de espera de 30 segundos debido a un procesamiento lento) y luego reanude el punto final en el panel de control. Una vez reanudado, Elido no reenvía automáticamente los eventos que se omitieron durante la pausa; reenvíelos manualmente desde el registro de entregas si necesita recuperar esos eventos.

Sí, active el modo raw-click en el punto final. En este modo, Elido entrega los eventos click.created individualmente, sin ventana de agregación, en los 2 segundos siguientes al clic. Tenga en cuenta que un espacio de trabajo con mucho tráfico puede generar miles de eventos por minuto en modo raw-click; asegúrese de que su receptor pueda manejar ese volumen. Para la mayoría de los casos de uso analítico, la agregación predeterminada de 5 segundos (hasta 100 clics por carga útil) es suficiente y genera muchas menos solicitudes HTTP.

Las cargas útiles de eventos individuales son inferiores a 10 KB. Las cargas útiles de clics por lotes (modo predeterminado) pueden contener hasta 100 eventos por lote, con un límite máximo de tamaño de carga útil de 100 KB. Si un lote supera los 100 KB, se divide automáticamente en varias entregas. Los campos de metadatos de gran tamaño en los clics (por ejemplo, URLs de remitente largas) se truncan a 2 KB por campo. Si su receptor impone un límite estricto al tamaño de la carga útil, configure el modo raw-click (un evento por entrega) en lugar del modo por lotes.

Utilice una herramienta como ngrok, Cloudflare Tunnel o localtunnel para exponer su servidor local con una URL HTTPS pública y, a continuación, registre esa URL como un punto final de webhook en su espacio de trabajo de prueba. Alternativamente, utilice el botón de prueba de envío de webhooks en el panel de control para enviar una carga útil de muestra de cualquier tipo de evento a un punto final registrado sin activar un evento real. La Elido CLI (elido webhook test --event click.created --endpoint https://...) también funciona para pruebas locales mediante scripts.

Los eventos generados durante una ventana de mantenimiento se ponen en cola en nuestro flujo de eventos y se entregan una vez finalizado el mantenimiento. La página de estado de Elido (status.elido.app) anuncia las ventanas de mantenimiento planificadas con antelación. El SLA de entrega de webhooks excluye las ventanas de mantenimiento anunciadas. Para una ventana de mantenimiento típica de 30 a 60 minutos, el margen de reintento de 72 horas garantiza que no se pierda ningún evento de forma permanente: se entregarán en el orden en que se generaron una vez que el punto final sea alcanzable de nuevo.