Guía de configuración de Webhook

¿Qué es un Webhook?

Webhook permite que SNSTracker envíe notificaciones automáticamente a tu servidor o aplicación cuando el contenido monitoreado cumple con los umbrales configurados. Por ejemplo, cuando las vistas de un video aumentan significativamente o cuando un canal gana nuevos seguidores, SNSTracker enviará una notificación a tu URL de webhook (normalmente en menos de 1 minuto).

Guía de configuración paso a paso

Paso 1: Prepara tu endpoint de Webhook

Antes de configurar en SNSTracker, necesitas tener listo un endpoint de webhook. Es una URL que puede recibir solicitudes HTTP POST.

Opciones para tu endpoint de webhook:

Tu propio servidor: https://api.tuempresa.com/webhook
Funciones en la nube: AWS Lambda, Google Cloud Functions, Azure Functions, etc.
Plataformas de automatización: Zapier, Make.com, n8n, etc.
Servicios de prueba: webhook.site (solo para pruebas)

Requisitos:

Debe usar HTTPS (la URL empieza con https://)
Debe aceptar solicitudes POST
Debe devolver un código de estado HTTP 200-299 en caso de éxito

Paso 2: Añade un destino de Webhook en SNSTracker

Ve a la página de Collections
- Inicia sesión en SNSTracker
- Haz clic en Collections en la barra lateral izquierda (en la sección Track)
- O ve directamente a: /dashboard/collections
Abre Manage Notify Targets
- En la página de Collections, busca y haz clic en el botón "Manage Notify Targets"
- Esto abre el cuadro de gestión de destinos de notificación
Añade un nuevo destino
- Haz clic en el botón "Add Target"
- Aparecerá un cuadro para crear un nuevo destino de notificación
Selecciona el tipo Webhook
- En el cuadro, busca el desplegable "Type"
- Selecciona "Webhook" de las opciones
Introduce la URL del Webhook
- En el campo "Webhook URL", introduce la URL de tu endpoint de webhook
- Ejemplo: https://api.tuempresa.com/webhook
- Importante: La URL debe empezar con https://
Añade un comentario (opcional)
- En el campo "Comment", puedes añadir una nota para recordar para qué sirve este webhook
- Ejemplo: "Webhook de producción para monitoreo de TikTok"
- Máximo 50 caracteres
Configura la clave de firma (opcional, recomendado para producción)
- En el campo "Extra", puedes añadir un objeto JSON con una clave de firma:
```
{
  "signature_key": "tu-clave-secreta-aqui"
}
```
- Esta clave se usará para verificar que las solicitudes sean auténticas
- Si no se proporciona, SNSTracker usará tu clave de API o la URL del webhook como clave de firma
Guarda el destino de webhook
- Haz clic en el botón "Save"
- Tu destino de webhook ya está creado y listo para usarse

Paso 3: Configura las reglas de notificación en la Collection

Abre la configuración de la Collection
- Vuelve a la página de Collections
- Encuentra la collection para la que quieres configurar notificaciones
- Haz clic en el botón Edit (o haz clic en el nombre de la collection para abrir la configuración)
Habilita Feed Notify (para videos/publicaciones)
- En la configuración de la collection, busca la sección "Feed Notify"
- Activa el interruptor "Enable Notifications"
- Selecciona tu destino de webhook en el desplegable "Notify Targets"
- Elige las "Metrics" que quieres monitorear:
  - Views
  - Engagement (likes + comments + shares)
- Define el valor de "Threshold":
  - Introduce un número (p. ej., 1000) para notificar cuando la métrica aumente en esa cantidad
  - Pon 0 para notificar después de cada actualización exitosa
- Haz clic en "Save" o "Update"
Habilita Channel Notify (para cuentas)
- En la misma configuración de la collection, busca la sección "Channel Notify"
- Activa el interruptor "Enable Notifications"
- Selecciona tu destino de webhook en el desplegable "Notify Targets"
- Elige las "Metrics" que quieres monitorear:
  - Followers
  - Followings
  - Likes
- Define el valor de "Threshold":
  - Introduce un número (p. ej., 500) para notificar cuando la métrica aumente en esa cantidad
  - Pon 0 para notificar después de cada actualización exitosa
- Haz clic en "Save" o "Update"
Verifica la configuración
- Asegúrate de que tanto el destino de webhook como las reglas de notificación estén guardadas
- Tu webhook ahora recibirá notificaciones cuando se cumplan los umbrales configurados

Paso 4: Prueba tu Webhook

Usa un servicio de pruebas (recomendado para la primera configuración)
- Visita webhook.site
- Copia la URL única proporcionada (p. ej., https://webhook.site/unique-id)
- Usa esta URL como tu webhook URL en el Paso 2
- Configura una notificación con umbral 0 (para dispararse ante cualquier cambio)
- Espera a que SNSTracker revise tu contenido
- Revisa webhook.site para ver si recibiste la notificación
Revisa los logs de tu endpoint
- Si usas tu propio servidor, revisa los logs del servidor
- Busca solicitudes POST entrantes de SNSTracker
- Verifica que el cuerpo de la solicitud contenga los datos esperados
Verifica el formato de la notificación
- La notificación debe ser un objeto JSON con:
  - title: Descripción de la notificación
  - type: "feed" o "channel"
  - timestamp: Cuándo se envió la notificación
  - data: Array de elementos que activaron la notificación

Cómo se envían las notificaciones Webhook

SNSTracker usa un mecanismo de agrupación para optimizar la entrega de webhooks:

Detección inmediata: Cuando un recurso monitoreado (feed o channel) se actualiza correctamente y cumple el umbral de notificación, se marca inmediatamente para notificación.
Ventana de agrupación de 1 minuto: En lugar de enviar notificaciones individuales de inmediato, SNSTracker acumula todas las notificaciones elegibles dentro de una ventana de 1 minuto.
Entrega consolidada: Al final de cada período de 1 minuto, todas las notificaciones de esa ventana se combinan en una sola solicitud de webhook y se envían juntas.

Escenario de ejemplo:

A las 10:00:15, el Feed A cumple el umbral → marcado
A las 10:00:45, el Feed B cumple el umbral → marcado
A las 10:01:00, tanto el Feed A como el Feed B se envían en una sola solicitud de webhook

Beneficios:

Reduce el número de solicitudes HTTP a tu endpoint
Mejora la eficiencia y reduce la carga del servidor
Evita el spam de notificaciones durante cambios rápidos de datos
Todas las notificaciones dentro del período de agrupación se incluyen en el array data

Nota: El retraso máximo entre que un recurso cumple el umbral y el envío del webhook es de 1 minuto. Esto garantiza notificaciones casi en tiempo real mientras se mantiene la eficiencia del sistema.

¿Qué datos recibirás?

Cuando se activa una notificación, recibirás una solicitud POST con datos JSON como estos:

{
  "title": "Notificación de SNSTracker: aumento de vistas del feed",
  "type": "feed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": [
    {
      "feed_id": "feed-123",
      "url": "https://www.tiktok.com/@user/video/123",
      "platform_name": "TikTok",
      "view_count": 10000,
      "like_count": 2000,
      "changed_views": 1000,
      "changed_engagement": 50
    }
  ]
}

Campos de datos de notificación de Feed

feed_id: Identificador único
url: Enlace directo al video/publicación
platform_name: Plataforma (TikTok, Instagram, etc.)
title: Título del contenido
description: Descripción del contenido
author_username: Nombre de usuario del creador
author_nickname: Nombre visible del creador
view_count: Vistas totales
like_count: Me gusta totales
comment_count: Comentarios totales
share_count: Compartidos totales
changed_views: Vistas incrementadas desde la última revisión
changed_engagement: Engagement incrementado (likes + comments + shares)

Campos de datos de notificación de Channel

id: Identificador único del canal
channel_url: Enlace directo al canal/perfil
platform_name: Nombre de la plataforma
nickname: Nombre visible
username: Nombre de usuario/handle
followers: Seguidores totales
followings: Total de cuentas seguidas
likes: Me gusta totales
changed_followers: Seguidores incrementados desde la última revisión
changed_followings: Followings incrementados desde la última revisión
changed_likes: Me gusta incrementados desde la última revisión

Seguridad: Verificación de firma

SNSTracker incluye una firma en el encabezado X-Signature para verificar la autenticidad de la solicitud. La clave de firma se determina por:

La signature_key en el campo Extra (si se proporciona)
Tu primera clave de API activa (si no se configura signature_key)
Tu URL de webhook (como respaldo)

Para uso en producción, se recomienda verificar la firma para asegurar que las solicitudes sean auténticas.

Solución de problemas

El webhook no recibe notificaciones

Revisa la URL del webhook
- Verifica que la URL sea correcta y accesible
- Asegúrate de que empiece con https://
- Prueba la URL manualmente con una solicitud POST
Revisa la configuración de notificaciones
- Verifica que las notificaciones estén habilitadas en tu Collection
- Comprueba que el destino de webhook esté seleccionado
- Asegúrate de que los umbrales estén configurados correctamente
Revisa el estado del endpoint
- Asegúrate de que tu endpoint esté en funcionamiento y accesible
- Revisa los logs del servidor para solicitudes entrantes
- Verifica que tu endpoint devuelva estado de éxito (200-299)

Problemas comunes

Problema: "Webhook URL already exists"
Solución: Cada URL de webhook solo se puede usar una vez por equipo. Usa una URL diferente o edita el destino existente.

Problema: No se disparan las notificaciones
Solución:

Establece el umbral en 0 para probar (notifica ante cualquier cambio)
Espera a que SNSTracker revise tu contenido (la revisión se realiza periódicamente)
Verifica que tu contenido realmente haya cambiado en la cantidad del umbral

Problema: Errores de tiempo de espera
Solución: Tu endpoint debe responder en un máximo de 30 segundos. Optimiza el tiempo de respuesta de tu endpoint.

¿Necesitas ayuda?

Si encuentras problemas:

Verifica que tu URL de webhook sea accesible
Revisa que la configuración de notificaciones esté habilitada
Asegúrate de que los umbrales estén configurados correctamente
Contacta con soporte si los problemas persisten

¡Feliz monitoreo! 🚀

Guía de configuración de Webhook

On this page