Guia de Configuração de Webhook

O que é Webhook?

Webhook permite que o SNSTracker envie automaticamente notificações para o seu servidor ou aplicação quando o conteúdo monitorado atingir os limites configurados. Por exemplo, quando as visualizações de um vídeo aumentam significativamente, ou quando um canal ganha novos seguidores, o SNSTracker enviará uma notificação para a sua URL de webhook (geralmente em até 1 minuto).

Guia de Configuração Passo a Passo

Passo 1: Prepare seu Endpoint de Webhook

Antes de configurar no SNSTracker, você precisa ter um endpoint de webhook pronto. Esta é uma URL que pode receber requisições HTTP POST.

Opções para o seu endpoint de webhook:

  1. Seu próprio servidor: https://api.yourcompany.com/webhook
  2. Funções na nuvem: AWS Lambda, Google Cloud Functions, Azure Functions, etc.
  3. Plataformas de automação: Zapier, Make.com, n8n, etc.
  4. Serviços de teste: webhook.site (apenas para testes)

Requisitos:

  • Deve usar HTTPS (URL começa com https://)
  • Deve aceitar requisições POST
  • Deve retornar status HTTP 200-299 em caso de sucesso

Passo 2: Adicionar Destino de Webhook no SNSTracker

  1. Navegue até a página Collections

    • Faça login no SNSTracker
    • Clique em Collections na barra lateral esquerda (na seção Track)
    • Ou vá diretamente para: /dashboard/collections
  2. Abra Manage Notify Targets

    • Na página Collections, encontre e clique no botão "Manage Notify Targets"
    • Isso abre a janela de gerenciamento de destinos de notificação
  3. Adicione um novo destino

    • Clique no botão "Add Target"
    • Uma janela aparecerá para criar um novo destino de notificação
  4. Selecione o tipo Webhook

    • Na janela, encontre o dropdown "Type"
    • Selecione "Webhook" nas opções
  5. Insira a URL do Webhook

    • No campo "Webhook URL", insira a URL do seu endpoint de webhook
    • Exemplo: https://api.yourcompany.com/webhook
    • Importante: A URL deve começar com https://
  6. Adicionar comentário (opcional)

    • No campo "Comment", você pode adicionar uma nota para lembrar para que serve este webhook
    • Exemplo: "Webhook de produção para monitoramento do TikTok"
    • Máximo de 50 caracteres
  7. Configurar chave de assinatura (opcional, recomendado para produção)

    • No campo "Extra", você pode adicionar um objeto JSON com uma chave de assinatura:
    {
      "signature_key": "your-secret-key-here"
    }
    • Essa chave será usada para verificar se as requisições são autênticas
    • Se não for fornecida, o SNSTracker usará sua chave de API ou a URL do webhook como chave de assinatura
  8. Salvar o destino de webhook

    • Clique no botão "Save"
    • Seu destino de webhook está criado e pronto para uso

Passo 3: Configurar Regras de Notificação na Collection

  1. Abra as configurações da Collection

    • Volte para a página Collections
    • Encontre a collection para a qual deseja configurar notificações
    • Clique no botão Edit (ou clique no nome da collection para abrir as configurações)
  2. Ativar Feed Notify (para vídeos/posts)

    • Nas configurações da collection, encontre a seção "Feed Notify"
    • Ative o switch "Enable Notifications" para ON
    • Selecione seu destino de webhook no dropdown "Notify Targets"
    • Escolha as "Metrics" que deseja monitorar:
      • Visualizações
      • Engajamento (curtidas + comentários + compartilhamentos)
    • Defina o valor de "Threshold":
      • Insira um número (ex.: 1000) para notificar quando a métrica aumentar nesse valor
      • Defina como 0 para notificar após cada atualização bem-sucedida
    • Clique em "Save" ou "Update"
  3. Ativar Channel Notify (para contas)

    • Nas mesmas configurações da collection, encontre a seção "Channel Notify"
    • Ative o switch "Enable Notifications" para ON
    • Selecione seu destino de webhook no dropdown "Notify Targets"
    • Escolha as "Metrics" que deseja monitorar:
      • Seguidores
      • Seguindo
      • Curtidas
    • Defina o valor de "Threshold":
      • Insira um número (ex.: 500) para notificar quando a métrica aumentar nesse valor
      • Defina como 0 para notificar após cada atualização bem-sucedida
    • Clique em "Save" ou "Update"
  4. Verificar configuração

    • Certifique-se de que tanto o destino de webhook quanto as regras de notificação foram salvos
    • Seu webhook agora receberá notificações quando os limites configurados forem atingidos

Passo 4: Testar seu Webhook

  1. Use um serviço de teste (recomendado para a primeira configuração)

    • Visite webhook.site
    • Copie a URL exclusiva fornecida (ex.: https://webhook.site/unique-id)
    • Use essa URL como seu webhook na Etapa 2
    • Configure uma notificação com limite 0 (para disparar em qualquer mudança)
    • Aguarde o SNSTracker verificar seu conteúdo
    • Verifique no webhook.site se você recebeu a notificação
  2. Verifique os logs do seu endpoint

    • Se estiver usando seu próprio servidor, verifique os logs do servidor
    • Procure por requisições POST recebidas do SNSTracker
    • Verifique se o corpo da requisição contém os dados esperados
  3. Verifique o formato da notificação

    • A notificação deve ser um objeto JSON com:
      • title: Descrição da notificação
      • type: "feed" ou "channel"
      • timestamp: Quando a notificação foi enviada
      • data: Array de itens que dispararam a notificação

Como as Notificações de Webhook São Enviadas

O SNSTracker usa um mecanismo de agrupamento para otimizar a entrega de webhooks:

  • Detecção imediata: Quando um recurso monitorado (feed ou canal) é atualizado com sucesso e atende ao seu limite de notificação, ele é imediatamente sinalizado para notificação.

  • Janela de agrupamento de 1 minuto: Em vez de enviar notificações individuais imediatamente, o SNSTracker acumula todas as notificações elegíveis dentro de uma janela de 1 minuto.

  • Entrega consolidada: No fim de cada período de 1 minuto, todas as notificações dessa janela são mescladas em uma única requisição de webhook e enviadas juntas.

Exemplo de cenário:

  • Às 10:00:15, o Feed A atinge o limite → sinalizado
  • Às 10:00:45, o Feed B atinge o limite → sinalizado
  • Às 10:01:00, ambos Feed A e Feed B são enviados em uma única requisição de webhook

Benefícios:

  • Reduz o número de requisições HTTP para seu endpoint
  • Melhora a eficiência e reduz a carga no servidor
  • Evita spam de notificações durante mudanças rápidas de dados
  • Todas as notificações dentro do período de agrupamento são incluídas no array data

Observação: O atraso máximo entre um recurso atingir o limite e o envio do webhook é de 1 minuto. Isso garante notificações quase em tempo real, mantendo a eficiência do sistema.

Que Dados Você Receberá?

Quando uma notificação é disparada, você receberá uma requisição POST com dados JSON como este:

{
  "title": "Notificação do SNSTracker: Visualizações do Feed Aumentaram",
  "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 Dados de Notificação de Feed

  • feed_id: Identificador único
  • url: Link direto para o vídeo/post
  • platform_name: Plataforma (TikTok, Instagram, etc.)
  • title: Título do conteúdo
  • description: Descrição do conteúdo
  • author_username: Nome de usuário do criador
  • author_nickname: Nome de exibição do criador
  • view_count: Total de visualizações
  • like_count: Total de curtidas
  • comment_count: Total de comentários
  • share_count: Total de compartilhamentos
  • changed_views: Visualizações aumentadas desde a última verificação
  • changed_engagement: Engajamento aumentado (curtidas + comentários + compartilhamentos)

Campos de Dados de Notificação de Canal

  • id: Identificador único do canal
  • channel_url: Link direto para o canal/perfil
  • platform_name: Nome da plataforma
  • nickname: Nome de exibição
  • username: Nome de usuário/handle
  • followers: Total de seguidores
  • followings: Total de contas seguidas
  • likes: Total de curtidas
  • changed_followers: Seguidores aumentados desde a última verificação
  • changed_followings: Seguindo aumentados desde a última verificação
  • changed_likes: Curtidas aumentadas desde a última verificação

Segurança: Verificação de Assinatura

O SNSTracker inclui uma assinatura no header X-Signature para verificar a autenticidade da requisição. A chave de assinatura é determinada por:

  1. A signature_key no campo Extra (se fornecida)
  2. Sua primeira chave de API ativa (se nenhuma signature_key estiver definida)
  3. A URL do seu webhook (como fallback)

Para uso em produção, é recomendado verificar a assinatura para garantir que as requisições sejam autênticas.

Solução de Problemas

Webhook não está recebendo notificações

  1. Verifique a URL do webhook

    • Verifique se a URL está correta e acessível
    • Certifique-se de que começa com https://
    • Teste a URL manualmente com uma requisição POST
  2. Verifique as configurações de notificação

    • Verifique se as notificações estão ativadas na sua Collection
    • Verifique se o destino de webhook está selecionado
    • Garanta que os limites estão definidos corretamente
  3. Verifique o status do endpoint

    • Certifique-se de que seu endpoint está rodando e acessível
    • Verifique os logs do servidor para requisições recebidas
    • Confirme que seu endpoint retorna status de sucesso (200-299)

Problemas Comuns

Problema: "Webhook URL already exists"
Solução: Cada URL de webhook só pode ser usada uma vez por equipe. Use uma URL diferente ou edite o destino existente.

Problema: Notificações não estão disparando
Solução:

  • Defina o limite como 0 para testar (notifica em qualquer mudança)
  • Aguarde o SNSTracker verificar seu conteúdo (a verificação acontece periodicamente)
  • Verifique se seu conteúdo realmente mudou pelo valor do limite

Problema: Erros de timeout
Solução: Seu endpoint deve responder em até 30 segundos. Otimize o tempo de resposta do seu endpoint.

Precisa de Ajuda?

Se você encontrar problemas:

  1. Verifique se a URL do webhook está acessível
  2. Verifique se as configurações de notificação estão ativadas
  3. Garanta que os limites estão configurados corretamente
  4. Entre em contato com o suporte se os problemas persistirem

Boas análises! 🚀