Artigos sobre: Integrações e Desenvolvedores

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