Experimente o Omnifox grátis 7 dias grátis. Sem cartão de crédito.
Guias

Guia da API para desenvolvedores: webhooks e eventos explicados

Guia tecnico da API de mensageria para desenvolvedores: como funcionam os webhooks, quais eventos escutar e boas praticas de assinatura, idempotencia e retentativas.

July 11, 2026
Guia da API para desenvolvedores: webhooks e eventos explicados
Neste artigo

    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.

    Pronto para testar no seu negócio?

    Reúna WhatsApp, Instagram, Messenger, e-mail e chamadas em uma só caixa de entrada e deixe a IA dar a primeira resposta. Configure hoje mesmo.

    7 dias grátis. Sem cartão de crédito.

    Comentários (0)

    Ainda não há comentários. Seja o primeiro a compartilhar.

    Deixe um comentário

    Seu email nunca é publicado. Os comentários são moderados antes de aparecer.

    Markdown suportado. HTML é removido.

    Leia mais

    Fale conosco no WhatsApp