Los webhooks del acortador de URL de Elido envían por POST un sobre JSON firmado a tu endpoint HTTPS cada vez que algo cambia en un espacio de trabajo: se crea, edita o elimina un enlace, caduca o alcanza su tope de clics, se invita a un miembro, se verifica un dominio. Cada petición lleva una cabecera X-Elido-Signature: v1=<hex>, que es HMAC-SHA256 sobre {timestamp}.{raw_body}, y una entrega fallida recibe tres intentos en unos veinte minutos.
Los clics tienen su propio evento, click.created, con sus propias reglas: un payload con privacidad reducida, un tope de frecuencia por endpoint y una opción para el tráfico de bots. La última sección lo trata. Este artículo es la mitad saliente de la superficie de la API; la guía rápida de la API y los SDK del acortador de URL cubre la mitad entrante, y smart links explicados es el artículo cornerstone de funciones de donde proceden los eventos de enlaces.
Qué eventos de enlaces disparan hoy un webhook
Cada evento de abajo llega a un endpoint de webhook que se suscribió a él por nombre. El formulario de nuevo endpoint del panel ofrece casillas para los ocho más comunes; la API acepta cualquier nombre de la lista.
| Evento | Se dispara cuando | Casilla del panel |
|---|---|---|
link.created | Se crea un enlace, uno a uno o en una importación masiva | sí |
link.updated | Cambian el destino, los ajustes o el estado, ediciones masivas, restauraciones | sí |
link.deleted | Se elimina un enlace, de uno en uno o en masa | sí |
link.expired | Un enlace supera su fecha de caducidad | solo API |
link.cap_reached | Un enlace alcanza su número máximo de clics | solo API |
link.broken | La comprobación de enlaces rotos ve que el destino falla | solo API |
click.created | Se contabiliza un clic (bots y escáneres omitidos salvo que se active) | sí, nunca preseleccionado |
workspace.created, workspace.updated | Se aprovisiona un espacio de trabajo o cambian sus ajustes | sí |
member.invited, member.removed | Se añade un miembro (directamente, por SCIM o con una invitación aceptada) o se elimina | sí |
member.role_changed | Cambia el rol de un miembro | solo API |
invitation.created, invitation.accepted | Se envía o se acepta una invitación | solo API |
domain.verified, domain.ssl_failed | Un dominio personalizado supera las comprobaciones de DNS, o sigue sin superarlas tras 24 horas | solo API |
audit.event | Cualquier entrada del registro de auditoría | sí |
Los enlaces cifrados añaden dos más, link.encrypted_created y link.encryption_rotated. Si prefieres no mantener la lista al día a mano, crea un endpoint siem: recibe todos los eventos del espacio de trabajo, incluidas las entradas de auditoría, sin ningún filtro de suscripción. La única excepción es click.created, que solo llega a los endpoints event que lo marcan.
Los eventos de facturación pasan por la misma cola. El servicio de facturación publica subscription.created, subscription.activated, subscription.paused, subscription.resumed, subscription.frozen, subscription.unfrozen, subscription.change_scheduled, subscription.change_canceled, usage.threshold_80, usage.threshold_100 y usage.overage_charged. Un endpoint siem también los recibe.
En la hoja de ruta, todavía no activos: filtros por endpoint como "solo enlaces de la carpeta X". Hasta entonces, filtra por data.slug o data.link_id en tu gestor.
Crear un endpoint de webhook con la API
Un endpoint pertenece a un espacio de trabajo. Lo creas con un POST a /v1/workspaces/{workspace_id}/webhooks:
curl -X POST "https://api.elido.app/v1/workspaces/$WORKSPACE_ID/webhooks" \
-H "Authorization: Bearer elido_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/elido",
"events": ["link.created", "link.updated", "link.deleted"],
"description": "CRM sync",
"kind": "event"
}'
La respuesta es 201 con el endpoint y, para los tipos event y siem, un secreto de un solo uso:
{
"endpoint": {
"id": 7,
"workspace_id": 42,
"url": "https://hooks.example.com/elido",
"events": ["link.created", "link.updated", "link.deleted"],
"is_active": true,
"description": "CRM sync",
"kind": "event",
"config": {},
"created_at": "2026-09-21T09:12:44Z"
},
"secret": "whsec_9f2c..."
}
Elido genera el secreto; tú no envías ninguno. Cópialo ahora, porque ninguna llamada posterior lo devuelve. kind admite seis valores. event y siem son las entregas JSON firmadas que trata este artículo. discord, telegram, slack y sentry remodelan los mismos eventos como un mensaje de chat o un evento de Sentry, se autentican mediante la URL o un token de bot cifrado y no llevan cabeceras HMAC.
Los planes importan al crear. Un endpoint event requiere Pro, Business o Enterprise, y un espacio de trabajo Free recibe 402 Payment Required (el panel abre en su lugar el diálogo de mejora de plan). Un endpoint siem requiere Business o Enterprise. Los canales de chat y Sentry no tienen restricción de plan. Los endpoints que ya existen siguen entregando si el espacio de trabajo baja de plan.
Permisos: leer endpoints y el registro de entregas requiere workspace.view. Crear, editar, eliminar, rotar un secreto o reenviar una entrega requiere workspace.edit, es decir, un administrador o propietario. Una clave de API funciona dentro del espacio de trabajo para el que se emitió y nunca por encima del rol elegido al crearla, así que una clave de nivel lector recibe un 403 en el POST anterior. Referencia completa: la documentación de webhooks.
El sobre del payload del webhook
Cada entrega firmada tiene el mismo sobre de cuatro campos. data contiene el registro que cambió, así que para los eventos de enlaces es la fila del enlace:
{
"type": "link.created",
"workspace_id": 42,
"data": {
"id": 91834,
"workspace_id": 42,
"domain_id": 3,
"slug": "spring-sale",
"destination_url": "https://shop.example.com/spring",
"title": "Spring sale landing",
"tags": ["newsletter"],
"status": "active",
"expires_at": null,
"max_clicks": null,
"redirect_status": 302,
"created_by_user_id": 17,
"created_at": "2026-09-21T09:14:02.184311Z"
},
"timestamp": "2026-09-21T09:14:02Z"
}
Ese ejemplo está recortado; el data real lleva todas las columnas del enlace, incluidas las reglas de segmentación, la carpeta, la campaña y los campos de escaneo. No hay ID de evento ni short_url en el cuerpo, así que construye la URL corta a partir de tu dominio y del slug si la necesitas. Los eventos programados envían en cambio un objeto más pequeño: link.expired tiene link_id, slug y destination_url, y link.cap_reached añade cap y clicks.
Una corrección que debes conocer si registraste payloads antes de la corrección de redacción: los campos secretos ahora se eliminan antes de que un payload salga de Elido. El password_hash de un enlace protegido con contraseña y el token de una invitación solían aparecer en data; ya no lo hacen, ni en las entregas nuevas ni en el registro de entregas. Si guardaste payloads antiguos, conviene purgar esos datos.
Verificar la cabecera X-Elido-Signature
Cada petición firmada lleva estas cabeceras:
X-Elido-Signature: v1=5d8f0c3e...
X-Webhook-Signature: v1=5d8f0c3e...
X-Webhook-Timestamp: 1790068442
X-Webhook-Event: link.created
X-Webhook-Delivery: 55120
User-Agent: Elido-Webhooks/1.0
Las dos cabeceras de firma contienen el mismo valor, y X-Webhook-Signature es el alias retrocompatible. Elido calcula HMAC-SHA256, tal como se define en el RFC 2104, con toda la cadena whsec_... como clave, sobre la marca de tiempo, un punto y los bytes del cuerpo en bruto. Al digest hexadecimal se le añade el prefijo v1=. No hay ningún campo t= dentro de la cabecera; la marca de tiempo vive en su propia cabecera.
En Node, firma los bytes en bruto, no un objeto reserializado. Express necesita express.raw({ type: "application/json" }) en esta ruta por esa razón:
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyElido(secret, headers, rawBody, toleranceSec = 300) {
const ts = headers["x-webhook-timestamp"] ?? "";
if (!/^\d+$/.test(ts)) return false;
if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;
const mac = createHmac("sha256", secret).update(`${ts}.`).update(rawBody);
const expected = Buffer.from("v1=" + mac.digest("hex"));
// During a rotation the old secret signs X-Elido-Signature-Previous.
return ["x-elido-signature", "x-elido-signature-previous"].some((name) => {
const got = Buffer.from(headers[name] ?? "");
return got.length === expected.length && timingSafeEqual(got, expected);
});
}
La comprobación de longitud importa: el timingSafeEqual de Node lanza una excepción con buffers de distinto tamaño en lugar de devolver false. La versión en Python con el módulo hmac estándar:
import hashlib
import hmac
import time
def verify_elido(secret: str, headers, raw_body: bytes, tolerance: int = 300) -> bool:
ts = headers.get("X-Webhook-Timestamp", "")
if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance:
return False
digest = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256)
expected = "v1=" + digest.hexdigest()
for name in ("X-Elido-Signature", "X-Elido-Signature-Previous"):
got = headers.get(name)
if got and hmac.compare_digest(got, expected):
return True
return False
Si la comprobación sigue fallando, la guía de verificación de firmas de webhooks tiene una versión en Go, un nodo Code de n8n y las causas habituales de un desajuste. La ventana de cinco minutos es una comprobación tuya, no nuestra. Elido estampa una marca de tiempo nueva en cada intento, reintentos incluidos, así que un reintento legítimo nunca parece obsoleto. Sin la ventana, cualquiera que hubiera capturado una petición podría reproducirla la semana siguiente y la firma seguiría coincidiendo.
La rotación es POST /v1/workspaces/{workspace_id}/webhooks/{id}/rotate-secret, o el botón Rotate de la página del endpoint. Recibes el nuevo secreto una sola vez. Durante los siete días siguientes, cada entrega lleva además X-Elido-Signature-Previous, firmada con el secreto antiguo, y por eso las dos funciones de arriba la prueban. Despliega el nuevo secreto en cualquier momento de esa semana y nada falla.
La política de reintentos del webhook
El worker de entregas recoge las entregas pendientes cada pocos segundos, así que un cambio en un enlace suele llegarte en segundos. Cualquier respuesta 2xx marca la entrega como completada. Un estado distinto de 2xx, un error de red o la falta de respuesta en 10 segundos cuenta como un intento fallido.
Tres intentos por entrega, veinte minutos de principio a fin. Es corto a propósito y, sinceramente, más corto de lo que yo elegiría para un receptor detrás de una VPN inestable. Una caída de dos horas de tu lado no queda cubierta por los reintentos automáticos. Lo que la cubre es el registro de entregas: GET /v1/workspaces/{workspace_id}/webhooks/{id}/deliveries lista cada entrega con su estado, código HTTP, latencia, número de intentos y hora del próximo reintento, y la página del endpoint muestra las mismas filas con un botón Retry. Retry, o POST .../deliveries/{delivery_id}/retry, rearma una entrega fallida o entregada con un presupuesto nuevo de tres intentos y devuelve 202. Una entrega aún pendiente recibe 409.
Algunos fallos se saltan los reintentos. Un endpoint de Telegram sin su chat_id, o un DSN de Sentry mal formado, se marca como fallido de inmediato, porque repetir la petición no arreglará la configuración. Para desconectar un endpoint sin eliminarlo, envía PUT con "is_active": false; los endpoints en pausa no reciben entregas nuevas.
Si tu gestor hace trabajo pesado, devuelve 200 primero y pon el trabajo en cola. El corte de diez segundos es donde un gestor lento pero correcto se convierte en un duplicado, lo que nos lleva a la deduplicación.
¿Planificas un receptor para tu equipo? La página de la función de webhooks muestra el lado del panel de todo esto.
Idempotencia y orden de los webhooks
Elido entrega al menos una vez. La sección de reintentos mostró una forma en que aparece un duplicado: tu gestor confirma el trabajo, luego se pasa de la ventana de diez segundos y Elido lo envía de nuevo. Un Retry manual reenvía a propósito.
Ambos casos conservan el mismo valor de X-Webhook-Delivery, porque es el ID de una entrega a un endpoint, no de un intento. Úsalo como clave:
CREATE TABLE elido_webhook_seen (
delivery_id BIGINT PRIMARY KEY,
received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- in the handler, inside the same transaction as your work:
INSERT INTO elido_webhook_seen (delivery_id) VALUES ($1)
ON CONFLICT (delivery_id) DO NOTHING
RETURNING delivery_id;
-- no row back means you've already handled this delivery
Dos endpoints suscritos al mismo evento reciben dos ID de entrega distintos, así que deduplica por endpoint. En reinicios poco frecuentes de nuestro lado, un evento puede ponerse en cola dos veces como entregas separadas; si una doble escritura te perjudicaría, añade una segunda protección sobre type más data.id más data.updated_at.
No hay promesa de orden. Las entregas salen primero por la más antigua pendiente, pero un reintento de un evento temprano puede llegar después de uno posterior. Compara data.updated_at con lo que tienes almacenado antes de sobrescribir un enlace, y no te apoyes en el timestamp del sobre para ordenar: solo tiene precisión de un segundo.
El webhook click.created
click.created envía una entrega firmada por cada clic contabilizado. No está en la ruta de redirección: la redirección publica el clic y sigue adelante, como explica el artículo sobre la ingesta de clics fire-and-forget, y el evento se construye más tarde a partir del clic almacenado. Cuenta con unos segundos entre el clic y el POST, no con milisegundos.
El objeto data tiene este aspecto:
{
"type": "click.created",
"workspace_id": 42,
"timestamp": "2026-11-12T10:04:31Z",
"data": {
"id": "clk_3_99120",
"link_id": 9183,
"workspace_id": 42,
"slug": "spring",
"host": "go.acme.example",
"short_url": "https://go.acme.example/spring",
"timestamp": "2026-11-12T10:04:29Z",
"country": "DE",
"device": "mobile",
"browser": "Safari",
"referer_host": "news.ycombinator.com",
"ip": "203.0.113.0",
"is_bot": false,
"is_scanner": false
}
}
Unas pocas reglas determinan lo que llega:
- La privacidad primero. El payload se construye después de aplicar los ajustes de privacidad de analíticas del espacio de trabajo. La IP es siempre solo la red truncada (/24 en IPv4, /48 en IPv6), y se omite por completo en el modo sin datos personales. El referente se recorta a su host; las rutas y las cadenas de consulta nunca salen.
- Los bots están desactivados por defecto. Los clics marcados como
is_botois_scanner(un escáner de seguridad del correo que precarga el enlace) se omiten salvo que marques "Include bot and scanner clicks" en el endpoint, o envíesconfig.include_bot_clicks: truepor la API. Los rastreadores conocidos y los bots de vista previa de enlaces nunca cuentan como clics, así que nunca se envían. - Un tope de frecuencia, no una cola. Cada endpoint recibe como máximo 50 eventos de clic por segundo. El exceso se descarta, no se retrasa, de modo que un enlace viral no puede enterrar tu receptor, y eso también significa que el webhook no es un libro de registro completo en los picos. Concilia con la API de analíticas si cada clic importa.
- Deduplica por
data.id. La entrega es al menos una vez, como la de cualquier otro evento.data.idse mantiene igual si un clic se procesa dos veces, yX-Webhook-Deliverycubre los reintentos de una misma entrega. - Mismos reintentos y misma firma. Tres intentos (ahora, +5 minutos, +15 minutos) y la comprobación de
X-Elido-Signaturede más arriba en este artículo.
Solo los endpoints event que marcan click.created lo reciben. El formulario del panel lo lista pero nunca lo preselecciona, y los endpoints de Discord, Telegram, Sentry y siem no lo reciben. Zapier (un Catch Hook en Webhooks by Zapier), Make (un Custom webhook) y n8n (un nodo Webhook) pueden usarlo como disparador.
Otras dos vías siguen teniendo sentido para los datos de clics. Los reenviadores de eventos convierten cada clic en un evento del lado del servidor en una herramienta que ya usas: eventos de clic en enlaces de Mixpanel, eventos de clic de Klaviyo en perfiles o métricas de redirección de Datadog para paneles de operaciones. Y la API de analíticas, GET /v1/analytics/workspaces/{workspace_id}/clicks/recent más la exportación clicks.csv, es el registro completo. Webhooks frente a polling para el seguimiento de clics recorre cuál encaja mejor.
Relacionado en el blog
- Webhooks frente a polling para el seguimiento de clics - cuándo empujar y cuándo tirar.
- Guía rápida de la API y los SDK del acortador de URL - la superficie entrante de la API.
- Ingesta de clics fire-and-forget - por qué los clics nunca esperan llamadas salientes.
- Eventos de clic en enlaces de Mixpanel - datos de clics como eventos del lado del servidor.
- Métricas de redirección de enlaces de Datadog - la salud de las redirecciones en un panel de operaciones.
- Verificar firmas de webhooks - comprobaciones HMAC en Node, Python, Go y n8n, y cómo depurar un desajuste.
Preguntas frecuentes
¿Envía Elido un webhook por cada clic en un enlace?
Sí, mediante el evento click.created: una entrega firmada por cada clic contabilizado, unos segundos después de que ocurra. Los clics de bots y de escáneres de seguridad se omiten salvo que el endpoint lo active, y cada endpoint está limitado a 50 eventos de clic por segundo; el exceso se descarta en lugar de ponerse en cola. Para un registro completo de un enlace viral, lee también la API de analíticas.
¿Cómo verifico la firma de un webhook de Elido?
Calcula HMAC-SHA256 sobre el valor de X-Webhook-Timestamp, un punto y el cuerpo en bruto de la petición, con tu secreto whsec_ como clave. Codifícalo en hexadecimal, añade el prefijo v1= y compáralo en tiempo constante con la cabecera X-Elido-Signature. Rechaza las marcas de tiempo con más de cinco minutos de antigüedad.
¿Cuántas veces reintenta Elido un webhook fallido?
Cada entrega recibe tres intentos: uno inmediato, otro cinco minutos después de un fallo y otro quince minutos después de ese. Cualquier estado distinto de 2xx, error de red o respuesta más lenta de diez segundos cuenta como fallo. Tras el tercero, la entrega se marca como fallida hasta que pulses Retry.
¿Cuál es la diferencia entre X-Elido-Signature y X-Webhook-Signature?
Nada salvo el nombre. Ambas cabeceras llevan la misma firma v1=. X-Elido-Signature es la principal, y X-Webhook-Signature se mantiene como alias retrocompatible, así que usa la primera en código nuevo. Durante una rotación de secreto, Elido envía además X-Elido-Signature-Previous, firmada con el secreto antiguo, durante siete días.
¿Cómo evito procesar dos veces el mismo webhook?
Guarda el valor de la cabecera X-Webhook-Delivery y omite cualquier petición cuyo valor ya hayas gestionado. Identifica una entrega a un endpoint y se mantiene igual en los reintentos automáticos y en los reenvíos manuales, así que basta con un índice único sobre él.
¿Quién puede crear o eliminar webhooks en un espacio de trabajo?
Los administradores y propietarios del espacio de trabajo. Listar endpoints y leer el registro de entregas requiere acceso de lectura; crear, editar, eliminar, rotar un secreto o reenviar una entrega requiere el permiso espacio de trabajo.edit. Las claves de API están limitadas al rol elegido cuando se creó la clave.
Prueba Elido
Pega una URL, obtén un enlace corto
Sin registro. El enlace vive 30 días. Crea una cuenta para conservarlo.
Se necesita una cuenta gratuita. El plan gratuito incluye 25 enlaces en total. ¿Ya tienes una cuenta? Iniciar sesión