Começando com Webhooks

Webhook é o Codewo avisando o seu sistema. Quando algo acontece (uma conversa é aberta, um contato muda, uma venda é registrada), o Codewo manda um POST com os dados para o endereço que você cadastrou. Assim o seu sistema não precisa ficar consultando a API de tempos em tempos para descobrir o que mudou.

O que é

Cada destino cadastrado é um endpoint: uma URL https:// do seu sistema, os eventos que ela quer receber e um segredo de assinatura (o signing secret, que começa com whsec_) usado para provar que o aviso veio mesmo do Codewo.

Fica em Configurações → Integrações → Webhooks.

• Depende do plano. Se Webhooks não aparece em Integrações, o plano da sua empresa não inclui o recurso.
• Permissões. Ver a tela pede a permissão Ver integrações. Criar, editar, testar, pausar e excluir pedem Gerenciar integrações.

Os 11 eventos

Grupo	Evento	Nome na tela	Quando dispara
Conversas	conversation.created	Conversa criada	Uma conversa nova é aberta, em qualquer canal
Conversas	conversation.assigned	Conversa atribuída	Muda o responsável (pessoa, equipe ou atendente virtual), inclusive quando a conversa fica sem responsável
Conversas	conversation.status_changed	Status da conversa alterado	O status muda sem ser resolução: aberta, pendente, em andamento, adiada ou spam, inclusive ao reabrir
Conversas	conversation.closed	Conversa resolvida	A conversa é resolvida
Contatos	contact.created	Contato criado	Um contato novo é cadastrado, inclusive o que nasce da primeira mensagem num canal
Contatos	contact.updated	Contato atualizado	Muda nome, e-mail, telefone, empresa, status, origem do cadastro, foto ou o dono da carteira
Contatos	contact.tag_added	Etiqueta adicionada ao contato	Uma etiqueta entra no contato (um evento por etiqueta)
Vendas	order.created	Venda registrada	Um pedido é registrado, por qualquer caminho
Vendas	order.status_changed	Status do pedido alterado	O pedido passa a contar como venda (confirmado) ou deixa de contar (cancelado ou de volta a rascunho)
Vendas	order.delivered	Pedido entregue	A entrega passa a Entregue, inclusive na retirada pelo cliente
Vendas	quote.accepted	Orçamento aceito	A proposta é aceita pelo cliente no link ou registrada pela equipe como aceita

Os eventos de Vendas só acontecem na empresa que usa orçamentos e pedidos.

Como funciona

Exemplo: o financeiro quer que o sistema de cobrança da empresa saiba toda vez que uma venda é registrada ou cancelada.

1. Em Configurações → Integrações → Webhooks, clique em Novo endpoint.
2. Preencha Nome (por exemplo, "Sistema de cobrança"), a Descrição se quiser, e a URL de destino. Só https:// é aceito.
3. Em Eventos, marque Venda registrada e Status do pedido alterado. Clique em Criar webhook.
4. Abre a janela Copie o signing secret agora. O segredo aparece uma única vez: copie, guarde numa variável de ambiente do servidor e clique em Já guardei o secret.
5. No seu sistema, receba o POST, valide a assinatura (veja abaixo) e responda com um código 2xx.
6. No cartão do endpoint, clique em Testar. Chega um evento de teste com dados fictícios, marcado com "_test": true. Neste exemplo, como os eventos marcados são de Vendas, o teste chega no formato de contato (veja as pegadinhas). Clique em Entregas para ver o que foi enviado e o que o seu servidor respondeu.

O que chega

O corpo é um JSON com quatro campos:

{
  "id": "01K5TXQ3F8Q7ZC1V3W9J2B6M4N",
  "type": "order.status_changed",
  "created_at": "2026-09-22T16:41:58-03:00",
  "data": { "...": "dados do evento" }
}

• id identifica a entrega e é o mesmo em todas as tentativas dela. Use-o para não processar o mesmo aviso duas vezes.
• type é o evento.
• data muda por grupo: nos eventos de conversa e contato, o objeto vem embrulhado (data.conversation, data.contact); nos de venda, os campos ficam direto em data.

Junto vêm três cabeçalhos próprios, cujos nomes terminam em -Event (o evento), -Delivery (o mesmo id do corpo) e -Signature (a assinatura). Os três nomes completos aparecem em qualquer requisição de teste que o seu servidor receber. Os de assinatura e de entrega também estão no quadro Como funciona, no fim da tela de Webhooks.

Validar a assinatura (HMAC-SHA256)

O cabeçalho de assinatura tem o formato t=<horário unix>,v1=<assinatura em hexadecimal>. Para validar:

1. Pegue o corpo cru da requisição, exatamente como chegou (sem converter para objeto).
2. Separe o cabeçalho pelas vírgulas: guarde o valor de t e TODOS os valores de v1.
3. Calcule HMAC-SHA256 do texto  t + "." + corpo_cru , usando como chave o segredo inteiro (com o whsec_).
4. Compare o resultado com cada v1, em tempo constante. Basta um bater.
5. Recuse se t tiver mais de 5 minutos (proteção contra reenvio malicioso).

Pode vir mais de um v1: nas 24 horas depois de uma rotação do segredo, o aviso sai assinado com o segredo novo e com o antigo.

Resposta, novas tentativas e pausa

• Sucesso é responder com código 2xx em até 10 segundos. Qualquer outro código, erro de conexão ou demora conta como falha.
• Novas tentativas. Uma entrega tem até 5 tentativas: a primeira na hora e as seguintes 30 segundos, 5 minutos, 30 minutos e 2 horas depois de cada falha. Todas com o mesmo id.
• Pausa automática. Na 5ª falha seguida do endpoint, somando todos os eventos, ele é pausado e o cartão mostra Pausado (auto). Quem criou o endpoint recebe o aviso "Webhook desativado automaticamente". Corrija o servidor e clique em Reativar.
• O que se perde. Enquanto o endpoint está pausado, os eventos não são guardados para depois. Depois de reativar, o que falhou antes da pausa pode ser reenviado, uma entrega por vez, em Entregas → Reenviar.

Pegadinhas comuns

• O segredo aparece uma vez só. Perdeu? Use Rotacionar secret no menu do endpoint: um segredo novo aparece e o antigo continua valendo por 24 horas.
• Os trechos de exemplo da janela do segredo são só um ponto de partida. Eles não tratam as duas assinaturas da rotação. Ajuste o código para aceitar qualquer v1, como no roteiro acima. Do contrário, nas 24 horas depois de uma rotação, o seu servidor pode recusar os avisos até o endpoint ser pausado.
• O teste usa o primeiro evento marcado. Se o primeiro for de Vendas, o teste chega no formato de contato, e não no de pedido.
• Reenviar gera um id novo. Para o seu sistema, é uma entrega nova.
• Endereço local não recebe. O Codewo não alcança localhost nem a rede interna da sua empresa. Para desenvolver, use um túnel que publique o seu computador num endereço https://.

Boas práticas

• Responda rápido e processe depois. Valide, guarde o aviso numa fila do seu lado e devolva 200. Processamento demorado vira timeout e nova tentativa.
• Crie o endpoint com alguém que acompanha os avisos. Só quem criou é avisado da pausa automática.

Veja também

• Webhooks de saída: guia completo: o conteúdo de cada evento, a rotação do segredo e o log de entregas.
• Chaves de API: criar, usar e revogar: para buscar os dados completos depois do aviso.
• Receber dados de outro sistema: o caminho inverso, com outro sistema avisando o Codewo.