Guia da API para desenvolvedores: webhooks e eventos explicados

Se voce vai construir sobre uma plataforma de mensageria, mais cedo ou mais tarde esbarra em dois conceitos: a API REST (seu codigo chama a plataforma) e os webhooks (a plataforma chama o seu codigo). Este guia da API de mensageria para desenvolvedores explica como eles se encaixam, quais eventos importam e como implementar um receptor de webhooks robusto que nao perca mensagens.

API REST vs webhooks: a direcao importa

A diferenca fundamental e quem inicia a comunicacao:

• API REST (push de saida): seu aplicativo faz uma requisicao HTTP para fazer algo: enviar uma mensagem, criar um contato, mover um deal, listar conversas. Voce controla o quando.
• Webhooks (push de entrada): a plataforma envia uma requisicao HTTP POST quando acontece algo: chega uma mensagem, muda o status de entrega, encerra uma conversa. Voce nao pergunta; e avisado.

Usar polling (consultar a API a cada X segundos por novidades) e ineficiente e lento. Os webhooks sao a forma correta de reagir em tempo real.

Anatomia de um webhook

Um evento de webhook tipico chega como um POST com um corpo JSON. Sua estrutura costuma incluir:

• Um event ou type que identifica o que aconteceu (por exemplo message.received, message.status, conversation.closed).
• Um timestamp do momento do evento.
• Um objeto data com a carga util: a mensagem, o contato, o canal, os metadados.
• Uma assinatura nos cabecalhos (HMAC) para verificar a autenticidade.

Seu endpoint deve responder rapido com um 200 OK. Se demorar ou retornar erro, a plataforma vai retentar, e e ai que os problemas comecam se voce nao projetou bem.

Eventos que voce quase sempre vai querer escutar

Embora cada plataforma tenha seu catalogo, estes sao os eventos base de qualquer integracao conversacional seria:

1. message.received — chegou uma mensagem de um cliente.
2. message.sent / message.status — sua mensagem foi enviada, entregue, lida ou falhou.
3. conversation.created — comecou um novo fio.
4. conversation.assigned — foi atribuida a um agente ou equipe.
5. conversation.closed — a conversa foi encerrada.
6. contact.created / contact.updated — mudancas no cadastro do cliente.
7. deal.stage_changed / deal.won — movimentos no pipeline de vendas.

O Omnifox, por exemplo, expoe mais de 40 tipos de eventos entre mensageria, CRM, workflows e chamadas, de modo que voce pode assinar apenas o que a sua integracao precisa, em vez de receber tudo.

Como construir um receptor robusto

Estas praticas separam uma integracao de brinquedo de uma de producao:

• Verifique a assinatura sempre. Calcule o HMAC do corpo com o seu segredo e compare com o cabecalho. Rejeite qualquer POST que nao bata; e a sua unica defesa contra webhooks falsos.
• Responda rapido, processe depois. Retorne 200 imediatamente e enfileire o trabalho pesado. Se processar de forma sincrona e demorar, vai provocar retentativas e duplicados.
• Seja idempotente. Os webhooks podem chegar mais de uma vez. Guarde o ID do evento e descarte os repetidos para nao criar o mesmo registro duas vezes.
• Trate a ordem. Os eventos nem sempre chegam em ordem. Use o timestamp do evento, nao a hora de recebimento, para reconstruir a sequencia real.
• Registre e monitore. Logue cada webhook recebido com o ID e o resultado. Quando algo falhar, voce vai querer poder reprocessar.
• Tenha um endpoint tolerante a retentativas. Retorne 5xx apenas se realmente quiser que retentem; retornar 4xx costuma marcar o evento como falha definitiva.

Retentativas e filas: o detalhe que quebra integracoes

A maioria das plataformas retenta um webhook falho com backoff exponencial por horas. Isso e bom (voce nao perde eventos), mas perigoso se a sua logica nao for idempotente: cada retentativa pode duplicar um contato ou disparar uma automacao duas vezes. A solucao e sempre a mesma: receba -> valide a assinatura -> responda 200 -> enfileire -> processe com deduplicacao por ID. Com esse padrao, nem um pico de trafego nem uma queda momentanea do seu servidor vao fazer voce perder ou duplicar dados.

Conclusao

Dominar os webhooks e a API REST e o que permite construir experiencias de mensageria reativas e confiaveis: voce reage em tempo real, mantem seus sistemas sincronizados e nao perde eventos. Verifique assinaturas, seja idempotente, responda rapido e enfileire o trabalho pesado; com isso voce cobre 90% dos problemas de producao. Se busca uma API limpa com eventos granulares e webhooks bem documentados para comecar hoje, explore o Omnifox e conecte o seu produto a conversa.