Webhooks: devolvendo a resposta do cliente para o seu sistema

Disparar mensagem por API é a metade fácil da integração. A metade que muda a operação é a volta: saber que a mensagem foi entregue, que o cliente respondeu, que a conversa foi encerrada, que o contrato foi assinado.

Webhook é o mecanismo dessa volta. Em vez de o seu sistema perguntar “aconteceu alguma coisa?” a cada minuto, a plataforma avisa no instante em que acontece.

Os eventos que valem a pena assinar

• mensagem.recebida: o cliente escreveu. Útil para atualizar status no seu sistema.
• mensagem.status: enviada, entregue, lida ou falha.
• atendimento.iniciado / encerrado: com fila, responsável e motivo de encerramento.
• contato.atualizado: quando dados do cadastro mudam na conversa.
• oportunidade.movida: mudança de etapa no funil.
• documento.assinado: fecha o ciclo de contrato.

Assine só o que você vai tratar. Endpoint que recebe evento e joga fora é dívida técnica com custo de banda.

Como receber sem se machucar

1. Responda rápido. Devolva 200 em milissegundos e processe depois, em fila interna. Processamento pesado dentro do webhook gera timeout e retentativa.
2. Trate duplicidade. Toda entrega confiável pode repetir. Guarde o id do evento e ignore o que já processou.
3. Não confie na ordem. Eventos podem chegar fora de sequência; use o carimbo de tempo do evento, não o da chegada.
4. Valide a assinatura. Confirme que o payload veio mesmo da plataforma antes de agir.
5. Registre tudo por um tempo. Quando alguém perguntar “por que o sistema fez isso?”, o log responde.

Um exemplo concreto

Cliente recebe confirmação de consulta e responde “não vou conseguir”.

• mensagem.recebida chega no seu sistema → status do agendamento vira “risco de falta”.
• A conversa entra na fila da recepção com prioridade.
• Atendente remarca; atendimento.encerrado chega com motivo “remarcado”.
• Seu sistema atualiza a agenda e libera o horário para a lista de espera.

Nada disso exige alguém olhando tela. É integração fazendo trabalho de gente.

Quando webhook não é a melhor ferramenta

Para carga inicial, migração ou reconciliação diária, use consulta em lote pela API. Webhook é para tempo real; relatório de fechamento é para lote. Misturar os dois gera sistema instável e difícil de auditar.

O par API + webhook é o que faz a plataforma de atendimento conversar com ERP, sistema de gestão e e-commerce sem planilha no meio. Os detalhes estão aqui.