Introdução

Webhooks são mecanismos modernos de integração entre sistemas que permitem a comunicação em tempo real por meio de notificações automáticas. Em vez de depender de consultas periódicas a uma API (o famoso "polling") para verificar se algo mudou, os webhooks funcionam de forma reativa: sempre que um evento específico ocorre em um sistema — como uma nova venda, cadastro de usuário ou atualização de status — uma requisição HTTP é automaticamente enviada para uma URL previamente configurada, contendo os dados relevantes do evento. Essa abordagem reduz significativamente o tempo de resposta entre sistemas e o uso de recursos, tornando os webhooks ideais para aplicações que demandam agilidade e automação.

Para acessar a documentação completa de Webhooks dentro da sua plataforma, basta seguir a seguinte base de URL: https://.mindz.com.br/api/v2/doc/#/#configurando-webhooks

Estando logado com sua conta de administrador vá em: Configurações > Webhook. Estando na página de webhooks clique no botão Novo webhook, será aberto um modal para que realize algumas configurações como as listadas abaixo:

• Nome: Defina um nome para a configuração de webhooks que esta criando;

• URL de callback: Informe a URL que receberá os eventos automáticos disparados pela sua plataforma;

• Segredo: Informe um segredo para que possa conferir a autenticidade dos eventos, ao recebe-los em seu sistema.

Neste mesmo modal você encontrará uma lista com todos os conjuntos de eventos possíveis de monitoramento no momento, e para cada conjunto de eventos, os respectivos e específicos eventos daquele grupo, assim como demonstrado abaixo:

Conjunto de eventos:

Eventos de um grupo:

Terminado suas configurações e, escolhidos todos os eventos que deseja que sejam monitorados em seu webhook clique no botão Criar.

Validação de Assinatura com HMAC

Para garantir a autenticidade e integridade dos dados recebidos, a Mindz utiliza HMAC-SHA256 com o segredo configurado no webhook. Quando um evento é disparado, a requisição HTTP POST incluirá um cabeçalho chamado:

webhook-signature: 682e6d0bxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxadade85bd

Essa assinatura é gerada com base no corpo da requisição e no segredo informado na criação do webhook.

Monitoramento e Logs

Indo em: Integrações > Webhook, clique no ícone destacado no print abaixo para pode acessar os logs de eventos.

Status possíveis:

• Sucesso: Requisição enviada com resposta válida (2xx)

• Erro: URL respondeu com erro (4xx ou 5xx)

• Expirado: Tentativas automáticas falharam após timeout

• Aguardando: Webhook criado, mas ainda não obteve uma resposta

Informações dos logs