Webhooks: suscríbase a eventos de enlaces y clics

Los webhooks envían eventos desde Elido a su servidor a medida que ocurren. Úselos en lugar de hacer polling a la API cuando necesite datos en tiempo real — los casos de uso típicos incluyen sincronizar metadatos de enlaces con su CRM, construir un dashboard personalizado o iniciar un pipeline de CI cuando se publica un enlace.

Agregar un endpoint de webhook#

Dashboard → Webhooks → New endpoint.
Pegue la URL a la que debemos hacer POST. Debe ser HTTPS — rechazamos HTTP plano en el momento de la creación.
Elija los tipos de eventos que desea. La lista completa está a continuación.
(Opcional) Pegue un signing secret o permítanos generar uno. El secret se muestra una vez; cópielo antes de salir de la página.
Save. Enviamos un evento de prueba de inmediato para que pueda confirmar que el endpoint es accesible.

Catálogo de eventos#

Los tipos de eventos actuales. Los nombres siguen el formato <resource>.<action> y permanecen estables entre versiones.

link.created — se creó un nuevo enlace corto.
link.updated — cambió la URL de destino, el slug, la fecha de expiración o la contraseña.
link.deleted — el enlace fue eliminado de forma suave (aún recuperable durante 30 días).
link.clicked.aggregated — cada 60 segundos enviamos los conteos de clics por enlace para la ventana anterior. No entregamos eventos de clic individuales a través de webhooks (el volumen aplastaría la mayoría de los endpoints) — use la exportación de clics para datos de eventos sin procesar.
domain.verified — la verificación DNS de un dominio personalizado fue exitosa.
domain.tls_renewed — Caddy renovó el certificado TLS para un dominio personalizado.
qr.generated — se renderizó un SVG/PNG de código QR.
abuse.flagged — nuestro escáner de URL marcó un destino como sospechoso.
member.invited / member.removed — cambios en la membresía del workspace.

Estructura del payload#

Cada evento tiene el mismo envelope:

{
  "id": "evt_2c8L9N4M5",
  "type": "link.created",
  "created_at": "2026-05-15T09:42:11.382Z",
  "workspace_id": 4123,
  "data": {
    "link_id": 891234,
    "slug": "spring-2026",
    "destination": "https://acme.com/spring-sale",
    "created_by": "user_5821"
  }
}

id es único por entrega. Úselo para idempotencia — si recibe el mismo id dos veces (porque reintentamos), omita el duplicado.

Verificación de firmas#

Firmamos cada cuerpo de webhook con HMAC-SHA256 usando el secret de su endpoint. La firma está en el encabezado Elido-Signature con el formato t=<unix_ts>,v1=<hex>.

Para verificar en Node:

import { createHmac } from "node:crypto";

function verify(secret: string, body: string, header: string): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=")),
  );
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${body}`)
    .digest("hex");
  return expected === parts.v1;
}

Incluimos el timestamp en el payload firmado para prevenir ataques de replay. Rechace eventos donde |now - t| > 300 segundos.

Reintentos#

Reintentamos las entregas fallidas (cualquier respuesta que no sea 2xx, o ninguna respuesta en 10 segundos) con backoff exponencial: 30s, 1m, 5m, 30m, 2h, 12h. Después de 6 fallos marcamos el endpoint como failing y dejamos de reintentar ese evento específico. El endpoint permanece suscrito; los nuevos eventos continúan intentando la entrega.

Si el endpoint permanece failing durante 5 entregas consecutivas → lo desactivamos automáticamente y enviamos un correo al propietario del workspace. Vuelva a habilitarlo en el dashboard una vez que haya solucionado su servidor.

Registro de entregas#

Abra cualquier webhook en el dashboard para ver las últimas 500 entregas, con código de estado, tiempo de respuesta y el cuerpo de solicitud/respuesta para cada una. Las entregas fallidas se pueden reproducir manualmente desde esta vista.

Pruebas locales#

Use el CLI de Elido para reenviar webhooks a localhost:

npx @elido/cli webhooks forward --url http://localhost:3000/webhooks

El CLI registra un endpoint temporal que dura hasta que presione Ctrl-C, hace un túnel de las entregas a su máquina e imprime el cuerpo de la solicitud para cada evento.

Límites#

20 endpoints por workspace (Pro), 100 (Business).
Tamaño máximo de payload firmado de 10 KB. Los payloads más grandes se dividen — data incluye un indicador truncated: true y una URL para obtener el cuerpo completo.
50 eventos por segundo sostenidos por endpoint. Los picos se ponen en cola.

Solución de problemas#

El endpoint reporta 401 en el registro de entregas. Su endpoint está verificando firmas con el secret incorrecto. Compare el secret en Webhooks → Endpoint → Settings con el que tiene almacenado su servidor.

Algunos eventos llegan dos veces. O reintentamos después de una respuesta lenta, o su endpoint expiró sin responder. Use el id del evento para idempotencia.

Los conteos de link.clicked.aggregated no coinciden con el dashboard de analytics. El dashboard es en tiempo real (dentro de los 30s del clic); el webhook tiene una ventana de 60s. También hay una pequeña discrepancia (~1%) porque los bots filtrados del dashboard aún se incluyen en los agregados sin procesar hasta que se cierra la ventana del filtro de bots.