Webhooks

Los webhooks te permiten recibir notificaciones en tiempo real sobre tus enlaces — tanto cuando se hacen clic como cuando se crean, actualizan o 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: Desencadena flujos de trabajo en Make o Zapier cuando se hace clic en enlaces
• Análisis personalizado: 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 de 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 casos de uso de automatización, nuestra integración de Make o integración de Zapier son más fáciles de configurar que webhooks personalizados. Incluyen desencadenantes de clic 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 ámbito — 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. Verifica el campo event de nivel superior para diferenciarlos:

Carga útil del webhook

Carga útil de clic

Cuando ocurre un clic, Linkly envía una solicitud POST con la siguiente carga útil 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": {
    "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 de carga útil

Información de evento

Objeto de enlace

Objeto de clic

Nota de privacidad: Las direcciones IP nunca se incluyen en las cargas útiles del webhook.

Carga útil 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, utiliza nuestras integraciones nativas:

• Integración de Make - Plataforma de automatización visual con desencadenantes de clic instantáneos
• Integración de Zapier - Conecta Linkly a 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 URL recibirán la misma carga útil cuando ocurra un clic.

Manejo de errores

• Los webhooks son fire-and-forget - Linkly no reintenta entregas fallidas
• Los fallos 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

• Utiliza 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

Prueba

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 la carga útil recibida
4. 4
   Una vez verificado, cambia a tu URL de webhook de producción

Acceso a la API

También puedes gestionar webhooks mediante programación 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.