nobug
    Glossário/Webhook
    Inovação

    Webhook

    Mecanismo de notificação HTTP automática que permite comunicação em tempo real entre sistemas.

    Webhook é um padrão de integração baseado em HTTP que permite que um sistema notifique outro automaticamente quando um evento ocorre, invertendo o modelo tradicional de polling (consulta periódica). Em vez de um sistema perguntar repetidamente "aconteceu algo?", o webhook envia uma requisição HTTP POST para uma URL pré-configurada assim que o evento acontece — em tempo real. Exemplos comuns: notificação de pagamento aprovado (Stripe, PagSeguro), novo commit no repositório (GitHub), lead cadastrado no CRM (HubSpot), mensagem recebida (WhatsApp Business API). Boas práticas incluem: verificação de assinatura (HMAC), idempotência, retry com backoff exponencial, timeout adequado, fila de processamento assíncrono e logging para debugging. Webhooks são fundamentais em arquiteturas event-driven e automações low-code/no-code.

    Como funciona na prática

    Na configuração, o sistema de origem recebe uma URL do sistema de destino e a lista de eventos que devem ser avisados, como pagamento confirmado ou pedido cancelado. Quando o evento acontece, a origem envia uma requisição com os dados em JSON, normalmente acompanhada de uma assinatura calculada com um segredo compartilhado. O destino verifica a assinatura, grava a mensagem, responde rapidamente com sucesso e processa o conteúdo depois, em fila. Se a resposta não vier ou indicar erro, a origem tenta de novo em intervalos crescentes. Por isso o destino precisa reconhecer mensagens repetidas e evitar processar duas vezes o mesmo evento.

    Quando faz sentido

    Webhooks fazem sentido quando um sistema precisa reagir rapidamente a algo que acontece em outro, sem ficar consultando a todo momento. Os exemplos são liberar um pedido assim que o pagamento é confirmado, criar um chamado quando um alerta dispara ou atualizar o CRM quando um formulário é preenchido. Eles reduzem carga e atraso em comparação com consultas periódicas. Por outro lado, exigem um endereço público, disponível e protegido para receber as chamadas. Quando os eventos podem ser perdidos sem grande impacto, ou quando o sistema de origem não oferece webhooks, consultas agendadas ainda são uma alternativa simples e válida.

    O que avaliar

    O cuidado principal é a segurança: valide sempre a assinatura, use HTTPS e não confie em dados recebidos sem conferência, porque qualquer um pode tentar enviar requisições à URL. Para ações críticas, como confirmar pagamento, consulte a API da origem antes de agir. Garanta idempotência, já que o mesmo evento pode chegar mais de uma vez ou fora de ordem. Responda rápido e processe em segundo plano, para não estourar o tempo limite da origem. Registre todas as chamadas recebidas e monitore falhas. Tenha um processo de conciliação periódica, porque mesmo com novas tentativas algum evento pode se perder e precisa ser recuperado.

    Este termo faz parte da área de Inovação. Veja como a NOBUG trabalha com integração de sistemas e APIs.