Webhooks

Los webhooks te permiten recibir notificaciones en tiempo real sobre tus enlaces — tanto cuando se hacen clic como cuando se crean, se actualizan o se eliminan. Linkly envía una solicitud POST a tu URL(s) especificada(s) con información detallada sobre cada evento.

Casos de uso

• Plataformas de automatización: Activa flujos de trabajo en Make o Zapier cuando se hace clic en los enlaces
• Análisis personalizados: Envía datos de clics a tu propio sistema de análisis
• Actualizaciones de CRM: Actualiza registros de clientes cuando hacen clic en enlaces
• Notificaciones en Slack: Recibe notificaciones en Slack cuando se hace clic en enlaces importantes
• Seguimiento de clientes potenciales: Realiza un seguimiento de cuándo los prospectos interactúan con tus enlaces

Consejo: Para la mayoría de los casos de uso de automatización, nuestra integración de Make o integración de Zapier son más fáciles de configurar que los webhooks personalizados. Incluyen activadores de clics instantáneos impulsados por webhooks, sin necesidad de codificación.

Nota: Si configuras webhooks en ambos niveles, ambos se activarán para clics en ese enlace.

Eventos

Cada webhook recibe todos los tipos de eventos para su alcance — un webhook a nivel de enlace obtiene eventos para ese enlace, un webhook a nivel de espacio de trabajo obtiene eventos para cada enlace en el espacio de trabajo. Comprueba el campo event de nivel superior para distinguirlos:

Payload del webhook

Payload de clic

Cuando ocurre un clic, Linkly envía una solicitud POST con el siguiente payload JSON:

{
  "event": "click",
  "timestamp": "2025-01-15T10:30:00Z",
  "link": {
    "id": 12345,
    "name": "My Campaign Link",
    "url": "https://example.com/landing-page",
    "full_url": "https://yourdomain.com/abc123",
    "domain": "yourdomain.com",
    "slug": "/abc123",
    "destination": "https://example.com/landing-page",
    "workspace_id": 1,
    "enabled": true,
    "cloaking": false,
    "forward_params": true,
    "block_bots": true,
    "public_analytics": false,
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "spring-sale",
    "og_title": "Special Offer",
    "og_description": "Check out our spring sale!",
    "rules": [
      {
        "what": "country",
        "matches": "US",
        "url": "https://example.com/us-landing"
      }
    ]
  },
  "click": {
    "id": "01KYPGEEPJSPR3S564QRBDGA1W",
    "country": "US",
    "is_eu_country": false,
    "platform": "desktop",
    "browser_name": "Chrome",
    "referer": "https://twitter.com/",
    "isp": "Comcast",
    "bot_name": null,
    "destination": "https://example.com/landing-page",
    "params": {
      "utm_source": "twitter"
    }
  }
}

Campos del payload

Información del evento

Objeto de enlace

Objeto de clic

Nota de privacidad: Las direcciones IP nunca se incluyen en los payloads de webhook.

Payload del ciclo de vida del enlace

Los eventos link.created, link.updated y link.deleted comparten una forma. No hay objeto click — obtienes el event, un timestamp y el link completo:

{
  "event": "link.created",
  "timestamp": "2026-06-20T10:30:00Z",
  "link": {
    "id": 12345,
    "name": "My Campaign Link",
    "url": "https://example.com/landing-page",
    "full_url": "https://yourdomain.com/abc123",
    "domain": "yourdomain.com",
    "slug": "/abc123",
    "workspace_id": 1,
    "enabled": true,
    "rules": []
  }
}

Integraciones de plataformas de automatización

Para una configuración más fácil sin codificación personalizada, usa nuestras integraciones nativas:

• Integración de Make - Plataforma de automatización visual con activadores de clics instantáneos
• Integración de Zapier - Conecta Linkly con miles de aplicaciones sin código

Ambas integraciones usan webhooks bajo el capó pero manejan toda la configuración automáticamente.

Mejores prácticas

Múltiples webhooks

Puedes agregar múltiples URLs de webhook (una por línea). Todas las URLs recibirán el mismo payload cuando ocurra un clic.

Manejo de errores

• Los webhooks son fire-and-forget - Linkly no reintenta entregas fallidas
• Las fallas de webhook nunca afectan la redirección - los usuarios siempre llegan a su destino
• Asegúrate de que tu endpoint de webhook responda rápidamente (< 5 segundos recomendado)

Seguridad

• Usa endpoints HTTPS para URLs de webhook
• Valida solicitudes entrantes en tu manejador de webhook
• Considera agregar un parámetro secreto a tu URL de webhook para verificación

Pruebas

1. 1
   Configura una URL de webhook usando un servicio como webhook.site o RequestBin
2. 2
   Haz clic en tu enlace
3. 3
   Inspecciona el payload recibido
4. 4
   Una vez verificado, cambia a tu URL de webhook de producción

Acceso a API

También puedes administrar webhooks programáticamente a través de la API:

POST   /api/v1/link/:link_id/webhooks
DELETE /api/v1/link/:link_id/webhooks/:hook_id
GET    /api/v1/link/:link_id/webhooks

POST   /api/v1/workspace/:workspace_id/webhooks
DELETE /api/v1/workspace/:workspace_id/webhooks/:hook_id
GET    /api/v1/workspace/:workspace_id/webhooks

Consulta la Documentación de API para más detalles.