API e webhooks

A chave de API deixa um sistema seu consultar e alterar dados do SocialSell. O webhook faz o caminho contrário: o SocialSell avisa o seu sistema quando algo acontece. Use os dois para integrar ERP, Zapier, n8n ou um backend próprio.

Antes de começar

• A página Desenvolvedores exige a ação Chaves de API, do grupo Integrações, API e SSO. Ela só liga em cargos que veem todas as conversas, todos os canais e todos os clientes, porque a chave enxerga a organização inteira. Sem ela, a tela avisa que você não tem permissão.
• O plano define quantas chaves ativas você pode ter, quais escopos libera e quantos endpoints de webhook cabem. Escopos fora do plano aparecem como Fora do plano, e a página de webhooks avisa quando o plano não os inclui.
• O endpoint do webhook precisa ser HTTPS.

Criar uma chave de API

1. Abra Configurações › Desenvolvedores e clique em Nova chave de API.
2. Dê um nome à chave, para reconhecê-la na lista e nos logs.
3. Escolha a Validade: Sem expiração, 30 dias, 90 dias ou 1 ano.
4. Em Atalhos, escolha Só leitura, Mensagens, CRM típico ou Todos, ou marque os Escopos um a um. Dê o menor acesso possível: Todos só se a integração precisar de tudo.
5. Clique em Criar chave de API.
6. Copie a Chave secreta agora. Ela não aparece de novo. Marque Guardei a chave e clique em Concluir.

A chave começa com sk_live_ e vai no cabeçalho de cada requisição: Authorization: Bearer sk_live_.... A lista em Chaves mostra escopos, uso nas últimas 24 horas e último uso. Para encerrar o acesso, clique em Revogar, digite o nome da chave e confirme: ela deixa de funcionar na hora.

Criar um webhook

1. Na aba Webhooks, clique em Criar webhook.
2. Informe o Nome do webhook e a URL do endpoint.
3. Marque os eventos que quer receber, como Contato criado ou Negócio criado. Use a busca para achar um evento. Seu endpoint recebe uma entrega para cada evento marcado.
4. Clique em Criar webhook.
5. Copie o Secret de assinatura, marque Guardei o secret e clique em Concluir. Ele também não aparece de novo.

Como o webhook entrega

Cada evento chega como um POST assinado. O seu endpoint precisa responder com status 2xx em até 10 segundos.

• Assinatura: o cabeçalho X-Webhook-Signature traz sha256= mais o HMAC-SHA256 do texto "{timestamp}.{corpo}", calculado com o secret. O timestamp vem em X-Webhook-Timestamp. Valide sempre antes de processar.
• Tentativas: se a entrega falha, o SocialSell tenta de novo até 5 vezes, com intervalos crescentes.
• Pausa automática: depois de 10 falhas seguidas, o webhook é pausado e a organização é avisada. Corrija o endpoint e clique em Reativar.

Cada webhook da lista tem Testar (envia um evento de teste), Entregas, Editar, Pausar ou Reativar, Rotacionar secret e Excluir. Ao rotacionar, o secret anterior para de valer na hora e o novo aparece uma única vez; atualize seu backend antes de fechar a janela.

Acompanhar

A Visão geral mostra requisições, taxa de erro e latência, e traz a Documentação completa da API em docs.socialsell.ai. A aba Logs lista as requisições e as entregas de webhook, e cada número da Visão geral leva a ela já filtrada. O prazo de retenção dos logs aparece na própria aba.

Os limites de requisições por minuto e por dia variam com o plano e estão em docs.socialsell.ai.

Dúvidas comuns

Perdi a chave ou o secret

Não dá para recuperar. Crie outra chave e revogue a antiga. No webhook, use Rotacionar secret.

Quem sai da empresa leva a chave junto?

Não. A chave pertence à organização, não à pessoa. Ao desativar alguém, o SocialSell lista as chaves que ela criou e deixa você revogá-las. Veja Convidar a equipe.

Recebi um erro 403

A chave não tem o escopo necessário ou o recurso não está no plano. Confira os escopos da chave em Chaves.