Skip to main content
Webhooks são a forma mais eficiente de integrar a SocialSell com sistemas externos. Em vez de a sua aplicação ficar perguntando para a API a cada segundo se algo mudou, a SocialSell avisa você imediatamente quando um evento ocorre.
“Pense nos webhooks como mensagens enviadas pela SocialSell para o seu sistema, sem que você precise ficar consultando a API o tempo todo.”

​
Por que usar webhooks?

Sem webhooks, a sua aplicação precisaria fazer polling constante:
“Esse contato foi atualizado?” — não. “E agora?” — não. “E agora?” — sim.
Isso é lento, caro em requisições e ainda assim pode perder eventos. Com webhooks, a SocialSell avisa você imediatamente assim que o evento acontece. Com isso você pode:
  • Sincronizar contatos criados na SocialSell com seu ERP ou CRM interno
  • Atualizar um negócio no seu sistema quando ele é ganho ou perdido
  • Disparar automações (e-mail, Slack, sistemas internos) quando uma mensagem é recebida
  • Registrar movimentações de funil em ferramentas de analytics
  • Acionar integrações via Zapier, n8n, Make ou código próprio

​
Como funciona na prática

1

Crie uma assinatura

Registre um endpoint HTTPS público no seu sistema via POST /v1/webhooks, informando os eventos que deseja receber.
2

A SocialSell envia o evento

Quando o evento ocorrer, a SocialSell faz um POST para a sua URL com o payload do evento em JSON.
3

Você valida e processa

Valide a assinatura HMAC para confirmar que o evento veio da SocialSell, processe o payload e responda com 200 OK.
4

Retentativas automáticas

Se seu endpoint não responder ou retornar erro, a SocialSell tentará novamente com backoff exponencial.

​
Criando sua primeira assinatura

Requer o escopo write:webhooks e plano Growth ou superior. 
curl -X POST https://api.socialsell.ai/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Integração ERP",
    "url": "https://meusistema.com/webhooks/socialsell",
    "events": ["contact.created", "deal.won", "deal.stage.changed"]
  }'
A resposta inclui o campo secret — armazene-o com segurança, pois ele não será exibido novamente: 
{
  "data": {
    "id": "664f1a2b3c4d5e6f78901234",
    "name": "Integração ERP",
    "url": "https://meusistema.com/webhooks/socialsell",
    "events": ["contact.created", "deal.won", "deal.stage.changed"],
    "status": "active",
    "secret": "whsec_a1b2c3d4e5f6...",
    "created_at": "2026-06-10T15:00:00.000Z"
  }
}
O campo secret é retornado apenas na criação e não pode ser recuperado depois. Armazene-o imediatamente como variável de ambiente no seu sistema.

​
Formato do payload

Todo evento tem o mesmo envelope: 
{
  "id": "evt_01jx8kz3m4n5p6q7r8s9t0u1v",
  "event": "deal.won",
  "organization_id": "664a1b2c3d4e5f6789012345",
  "created_at": "2026-06-10T15:30:00.000Z",
  "data": {
    ...
  }
}
CampoTipoDescrição
idstringID único do evento — use para deduplicação
eventstringNome do evento (ex: deal.won)
organization_idstringID da organização
created_atstringTimestamp ISO 8601 do momento do evento
dataobjectPayload específico do evento

​
Eventos disponíveis

EventoDescrição
contact.createdUm novo contato foi criado
contact.updatedUm contato foi atualizado
deal.createdUm novo negócio foi criado
deal.stage.changedUm negócio mudou de etapa no funil
deal.wonUm negócio foi marcado como ganho
deal.lostUm negócio foi marcado como perdido
message.receivedUma mensagem foi recebida de um contato

​
Próximos passos

Segurança

Como validar a assinatura HMAC de cada entrega.

Política de entregas

Timeouts, retentativas e desativação automática.

Gerenciar assinaturas

Endpoints CRUD para gerenciar suas assinaturas.