Introdução aos Webhooks

Em vez de a sua aplicação perguntar de tempos em tempos se algo mudou, a SocialSell avisa: quando o evento acontece, sai um POST assinado para a URL que você cadastrou. Com isso dá para:

Espelhar conversas inteiras em um sistema externo (assinando message.received e message.sent)
Sincronizar contatos, empresas e negócios com o ERP ou o CRM interno
Ser avisado no instante em que um canal de atendimento cai (channel.disconnected)
Acordar um sistema de atendimento quando a IA devolve a conversa para uma pessoa (ai_agent.handoff)
Apagar o registro do outro lado quando algo é excluído aqui (contact.deleted, deal.deleted)
Disparar cobrança, contrato ou onboarding em deal.won e proposal.accepted
Monitorar saldo de créditos e status de pagamento antes de virar problema

Como funciona

Cadastre um endpoint

Registre uma URL HTTPS pública em POST /v1/webhooks, escolhendo os eventos que quer receber.

Guarde o secret

A resposta da criação traz o secret. Ele só aparece nesse momento.

Valide a assinatura

Cada entrega vem assinada em X-Webhook-Signature. Confira antes de processar — veja Segurança e verificação.

Responda 2xx rápido

Você tem 10 segundos. Responda e processe em background; falhas são retentadas com backoff.

Criando sua primeira assinatura

Requer o escopo write:webhooks e um plano com o módulo Webhooks e pelo menos um endpoint liberado.

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": ["deal.won", "proposal.accepted", "channel.disconnected"]
  }'

{
  "data": {
    "id": "664f1a2b3c4d5e6f78901234",
    "name": "Integração ERP",
    "url": "https://meusistema.com/webhooks/socialsell",
    "events": ["deal.won", "proposal.accepted", "channel.disconnected"],
    "status": "active",
    "secret": "whsec_a1b2c3d4e5f6...",
    "last_delivery_at": null,
    "last_failure_at": null,
    "consecutive_failures": 0,
    "created_at": "2026-08-20T14:30:00.000Z",
    "updated_at": "2026-08-20T14:30:00.000Z"
  }
}

O secret só é devolvido na criação e na rotação. Guarde como variável de ambiente na hora. Se perder, use POST /v1/webhooks/{id}/rotate-secret para gerar outro.

A URL precisa ser HTTPS e resolver para um endereço público — localhost, redes privadas e faixas reservadas são recusadas, tanto no cadastro quanto no momento de cada entrega.

O envelope

Todo evento chega no mesmo formato:

{
  "id": "evt_9f2c1a7b4e8d0c3a5b6f7e81",
  "type": "deal.won",
  "created_at": "2026-08-20T14:30:00.000Z",
  "organization_id": "664a1b2c3d4e5f6789012345",
  "data": {
    "deal": { "id": "664g2h3i...", "title": "Implantação — Empresa XYZ", "value": 48000, "status": "won" },
    "reason": "Melhor custo-benefício"
  }
}

Campo	Tipo	Descrição
`id`	string	Identificador único da entrega. Use para deduplicar.
`type`	string	Nome do evento.
`created_at`	string	ISO 8601 do momento do evento.
`organization_id`	string	Organização dona do evento.
`data`	object	Conteúdo específico do evento.

Dentro de data, o recurso vem nomeado (data.deal, data.contact, data.task) e no mesmo formato que a API v1 devolve nos endpoints de leitura. Quem já consome a API não precisa aprender um segundo formato.

Eventos disponíveis

São 47 eventos, em 13 grupos. A referência de eventos traz o payload exato de cada um.

Grupo	Cobre
Contatos	criação, atualização, exclusão, etiquetas e notas
Empresas	criação, atualização, exclusão e notas
Negócios	criação, etapa, ganho, perdido, responsável, funil, exclusão e notas
Propostas	criada, visualizada, aceita e recusada
Tarefas	criada, concluída, vencendo e atrasada
Conversas	iniciada, reaberta, atribuída e encerrada
Mensagens	recebida, enviada e editada
Canais	conectado e desconectado (WhatsApp, Instagram, Messenger)
Inteligência artificial	handoff do agente para humano
Disparos	concluído e interrompido
Importações	concluída e falhou
Equipe	membro entrou e saiu
Créditos e cobrança	saldo baixo, saldo zerado, pagamento e troca de plano

Eventos e a API v1

Escrever pela API v1 dispara 21 dos 47 eventos do catálogo:

Ação pela API v1	Evento
Criar, atualizar ou excluir contato	`contact.created` · `contact.updated` · `contact.deleted`
Adicionar ou remover tag de contato	`contact.tag.added` · `contact.tag.removed`
Criar nota em contato	`contact.note.added`
Criar, atualizar ou excluir empresa	`company.created` · `company.updated` · `company.deleted`
Criar, mover, ganhar, perder ou excluir negócio	`deal.created` · `deal.stage.changed` · `deal.won` · `deal.lost` · `deal.deleted`
Trocar responsável do negócio	`deal.assigned`
Mover negócio para outro funil	`deal.pipeline.transferred`
Criar nota em negócio	`deal.note.added`
Criar ou concluir tarefa	`task.created` · `task.completed`
Atribuir ou fechar conversa	`conversation.assigned` · `conversation.closed`

Os 26 restantes existem porque nascem fora da API: mensagens recebidas e enviadas, conexão e queda de canal, handoff de agente de IA, propostas, disparos, importações, entrada e saída de membros, créditos e cobrança. Eles chegam normalmente, venham de onde vierem.

Como a escrita pela API dispara o webhook, uma integração que escreve e ouve recebe o eco da própria ação. Deduplique por id do evento e, se precisar distinguir, o payload de eventos originados pela API traz o contexto da chamada.

Não existe endpoint de notas de empresa na v1. O evento company.note.added só dispara por ação no painel.

Limites por plano

Plano	Endpoints
Starter	— (webhooks não disponíveis)
Growth	3
Scale	10
Enterprise	25

Esses são os limites dos planos padrão. Planos personalizados podem ter outra quantidade, definida no contrato. Cada endpoint pode assinar quantos eventos quiser. Se a organização perder o módulo ou tiver o limite reduzido a zero, os endpoints são pausados e a organização é avisada no painel.

Gerenciando pelo painel

Tudo o que a API faz também está em Configurações → Desenvolvedores → Webhooks: criar, editar, pausar, rotacionar secret, disparar evento de teste, ver o log de entregas e reenviar. Precisa da permissão manage_api_keys.

Próximos passos

Referência de eventos

Os 47 eventos com o payload exato de cada um.

Segurança

Validar a assinatura HMAC em Node, Python, PHP e Go.

Política de entregas

Timeout, retentativas, pausa automática e reenvio.

Visão geral

Eventos

Gerenciar assinaturas

Como funciona

Criando sua primeira assinatura

O envelope

Eventos disponíveis

Eventos e a API v1

Limites por plano

Gerenciando pelo painel

Próximos passos

Referência de eventos

Segurança

Política de entregas

​Como funciona

​Criando sua primeira assinatura

​O envelope

​Eventos disponíveis

​Eventos e a API v1

​Limites por plano

​Gerenciando pelo painel

​Próximos passos

Referência de eventos

Segurança

Política de entregas

Como funciona

Criando sua primeira assinatura

O envelope

Eventos disponíveis

Eventos e a API v1

Limites por plano

Gerenciando pelo painel

Próximos passos