Skip to main content

O que são webhooks?

Webhooks permitem que a SocialSell envie notificações automáticas para o seu sistema quando eventos ocorrem — como um novo contato criado, um negócio ganho ou uma mensagem recebida. Em vez de fazer polling constante na API, você recebe os dados imediatamente.

Eventos disponíveis

Mais eventos serão adicionados em versões futuras. Acompanhe o roadmap em socialsell.canny.io.

Criando uma assinatura

Requer o escopo write:webhooks e plano Growth ou superior.
A resposta inclui o campo secret — armazene-o com segurança para validar as entregas:
O campo secret é retornado apenas na criação. Não é possível recuperá-lo depois. Armazene-o como variável de ambiente.

Formato do payload

Cada evento entregue tem o seguinte formato:

Validando a assinatura

Cada requisição inclui o header X-SocialSell-Signature com um HMAC-SHA256 do corpo usando seu secret:
Sempre valide a assinatura antes de processar o payload:

Política de retentativas

A SocialSell tenta entregar cada evento com as seguintes regras:
  • Timeout: 10 segundos para o endpoint responder
  • Sucesso: resposta HTTP 2xx
  • Falha: qualquer outro status ou timeout
  • Retentativas: após falha, tenta novamente com backoff exponencial
  • Desativação automática: após múltiplas falhas consecutivas, a assinatura é pausada automaticamente (campo consecutive_failures)
Responda com 200 OK o mais rápido possível e processe o evento de forma assíncrona (ex: em uma fila). Isso evita timeouts causados por processamento lento.

Gerenciamento de assinaturas

Idempotência

Eventos podem ser entregues mais de uma vez em casos de falha. Use o campo id do evento para garantir idempotência no processamento: