Introdução aos Webhooks - SocialSell API

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

Crie uma assinatura

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

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.

Você valida e processa

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

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": {
    ...
  }
}

Campo	Tipo	Descrição
`id`	string	ID único do evento — use para deduplicação
`event`	string	Nome do evento (ex: `deal.won`)
`organization_id`	string	ID da organização
`created_at`	string	Timestamp ISO 8601 do momento do evento
`data`	object	Payload específico do evento

Eventos disponíveis

Evento	Descrição
`contact.created`	Um novo contato foi criado
`contact.updated`	Um contato foi atualizado
`deal.created`	Um novo negócio foi criado
`deal.stage.changed`	Um negócio mudou de etapa no funil
`deal.won`	Um negócio foi marcado como ganho
`deal.lost`	Um negócio foi marcado como perdido
`message.received`	Uma 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.

​Por que usar webhooks?

​Como funciona na prática

​Criando sua primeira assinatura

​Formato do payload

​Eventos disponíveis

​Próximos passos

Segurança

Política de entregas

Gerenciar assinaturas

Por que usar webhooks?

Como funciona na prática

Criando sua primeira assinatura

Formato do payload

Eventos disponíveis

Próximos passos