O que é webhook? Como funcionam os webhooks do sona.to

O que é webhook? É uma mensagem que um app envia a outro no momento em que algo acontece, para que o segundo app não precise ficar perguntando. Você dá ao primeiro app um endereço, e ele envia para lá os detalhes de cada evento assim que ele ocorre. Este guia explica como os webhooks funcionam, como conferir se um webhook é legítimo e o que o sona.to envia, também resumido na página de webhooks.

O que é um webhook?

A maioria dos apps troca dados de duas formas. Com uma API, o seu sistema pergunta: "o post já foi publicado?", e pergunta de novo mais tarde se a resposta for não. Com um webhook, o app avisa você: quando o post é publicado, ele envia uma requisição para um endereço que você escolheu, com os detalhes do post.

Um webhook é, portanto, uma requisição HTTP, normalmente um POST com corpo em JSON, enviada a uma URL que você controla. Essa URL pode ser o seu próprio servidor ou um endereço de webhook fornecido pelo n8n, Zapier, Make, Slack ou outro serviço que inicia um fluxo quando a requisição chega.

Webhook ou API

Uma API serve para perguntar e alterar: listar posts, criar um post, ler números. Um webhook serve para ser avisado. A maioria das integrações usa os dois: a API para criar um post e um webhook para saber quando ele foi publicado ou falhou. Consultar uma API várias vezes seguidas desperdiça requisições e, mesmo assim, você fica sabendo tarde, enquanto um webhook chega assim que o evento acontece.

Como verificar um webhook

Qualquer pessoa que conheça o endereço do seu webhook pode enviar uma requisição falsa para ele, então um webhook bem feito é assinado. O remetente calcula uma assinatura a partir do corpo e de um segredo compartilhado, geralmente com HMAC SHA-256, e coloca essa assinatura num cabeçalho. O seu lado calcula a mesma assinatura com o mesmo segredo e compara as duas com uma comparação de tempo constante. Se forem diferentes, a requisição é ignorada.

Incluir um timestamp nos dados assinados também impede repetições: uma requisição capturada uma vez não pode ser enviada de novo mais tarde, porque o timestamp dela já está velho demais.

Webhooks no sona.to

O sona.to envia webhooks para quatro eventos: um post foi publicado, um post falhou, uma auditoria de site terminou e uma auditoria de site falhou. Você escolhe quais eventos cada webhook recebe, então um aviso no chat pode ouvir só as falhas enquanto uma planilha de relatório recebe tudo. O payload usa os mesmos nomes de campo da API do sona.to.

Configuração. Na página da API do seu painel, cole o endereço, marque os eventos e salve. O segredo de assinatura aparece uma única vez, nesse momento, então copie-o na hora.

Assinatura. Cada entrega traz um cabeçalho com um timestamp e um HMAC SHA-256 do timestamp e do corpo, feito com o seu segredo. Rejeite requisições cujo timestamp tenha mais de alguns minutos.

Novas tentativas. Se o seu endereço estiver fora do ar ou devolver um erro, a entrega é tentada de novo depois de 60 segundos, 5 minutos e 30 minutos. Cada tentativa fica registrada com o código de status e a duração. Um endereço que continua falhando é desativado, e você pode reativá-lo depois de corrigido.

Segurança. O endereço precisa usar https e apontar para um servidor público. Endereços em redes privadas são recusados ao salvar e de novo na entrega, e redirecionamentos não são seguidos.

Webhooks com n8n, Zapier e Make

Os apps do sona.to para n8n, Zapier e Make têm gatilhos prontos para os mesmos quatro eventos, então você não precisa colar nenhum endereço: adicione o gatilho e o app configura o webhook. Veja automação de redes sociais com n8n, Zapier e Make.

Todos os detalhes, com um exemplo de verificação de assinatura, estão na documentação da API.

Perguntas frequentes

Webhook é a mesma coisa que API?

Não. Uma API responde quando você pergunta. Um webhook envia uma mensagem quando algo acontece.

Os webhooks do sona.to são gratuitos?

Os webhooks estão incluídos em todos os planos, junto com a API.

O que acontece se o meu servidor estiver fora do ar?

O sona.to tenta de novo três vezes ao longo de cerca de meia hora. Se as entregas continuarem falhando, o webhook é desativado até você reativá-lo.