Configurando Webhooks
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://<NOMEDASUAPLATAFORMA>.mindz.com.br/api/v2/doc/#/#configurando-webhooks
Configuração
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: Configuraçõ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
Campo | Descrição |
---|---|
Nome | Evento que gerou o webhook (ex: Usuário/Matricula, Usuário/Login) |
URL | Endereço para o qual o webhook foi enviado |
Status | Resultado da tentativa de envio |
Criado | Data e hora em que o webhook foi registrado |
Última tentativa | Último momento de tentativa de envio |
Botão de Reenvio | Permite reenviar manualmente em caso de falha |
Qualquer dúvida estamos à disposição em nosso suporte ao vivo.
Atualizado em: 19/06/2025