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:
- Seu próprio servidor:
https://api.yourcompany.com/webhook - Funções na nuvem: AWS Lambda, Google Cloud Functions, Azure Functions, etc.
- Plataformas de automação: Zapier, Make.com, n8n, etc.
- 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
-
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
-
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
-
Adicione um novo destino
- Clique no botão "Add Target"
- Uma janela aparecerá para criar um novo destino de notificação
-
Selecione o tipo Webhook
- Na janela, encontre o dropdown "Type"
- Selecione "Webhook" nas opções
-
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://
-
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
-
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
-
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
-
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)
-
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"
-
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"
-
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
-
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
-
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
-
Verifique o formato da notificação
- A notificação deve ser um objeto JSON com:
title: Descrição da notificaçãotype: "feed" ou "channel"timestamp: Quando a notificação foi enviadadata: Array de itens que dispararam a notificação
- A notificação deve ser um objeto JSON com:
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 únicourl: Link direto para o vídeo/postplatform_name: Plataforma (TikTok, Instagram, etc.)title: Título do conteúdodescription: Descrição do conteúdoauthor_username: Nome de usuário do criadorauthor_nickname: Nome de exibição do criadorview_count: Total de visualizaçõeslike_count: Total de curtidascomment_count: Total de comentáriosshare_count: Total de compartilhamentoschanged_views: Visualizações aumentadas desde a última verificaçãochanged_engagement: Engajamento aumentado (curtidas + comentários + compartilhamentos)
Campos de Dados de Notificação de Canal
id: Identificador único do canalchannel_url: Link direto para o canal/perfilplatform_name: Nome da plataformanickname: Nome de exibiçãousername: Nome de usuário/handlefollowers: Total de seguidoresfollowings: Total de contas seguidaslikes: Total de curtidaschanged_followers: Seguidores aumentados desde a última verificaçãochanged_followings: Seguindo aumentados desde a última verificaçãochanged_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:
- A
signature_keyno campo Extra (se fornecida) - Sua primeira chave de API ativa (se nenhuma signature_key estiver definida)
- 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
-
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
-
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
-
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:
- Verifique se a URL do webhook está acessível
- Verifique se as configurações de notificação estão ativadas
- Garanta que os limites estão configurados corretamente
- Entre em contato com o suporte se os problemas persistirem
Boas análises! 🚀