Configuração de webhooks

Um webhook avisa automaticamente a um sistema externo (seu backend, um LMS, um CRM) sempre que um evento acontece com suas credenciais digitais — por exemplo, quando alguém aceita uma credencial — sem que você precise consultar a API da Acreditta periodicamente para saber disso.

Onde configurá-los

  1. Vá para Configurações → Integrações → API.
  2. Abra a aba Webhooks.

🔎 Observação: isso fica na aba API, não em Ferramentas externas — essa outra seção é para integrações de login e LMS (Microsoft, Google, Moodle, Canvas, etc.), um assunto diferente.

⚠️ Importante: os webhooks exigem um plano que inclua esse recurso. Se sua organização não tiver, qualquer chamada à API de webhooks responde 400 e esta aba é substituída por um aviso para fazer upgrade do seu plano. Veja Planos e limites.

Se você não tiver nenhum configurado, verá a mensagem “Nenhum webhook configurado”. Clique em + Novo Webhook para criar o primeiro.

Criar um webhook

Preencha:

  • URL do Endpoint (Serviço Web): o endereço do seu sistema que vai receber a notificação. Obrigatório.
  • Tipo de autenticação: como seu backend vai validar que a notificação realmente vem da Acreditta.
  • Eventos: o que você vai escutar. Você deve marcar pelo menos um.

Tipos de autenticação

  • Assinatura HMAC (Recomendado): a Acreditta gera uma Secret Key ao salvar o webhook, que você deve usar no seu backend para validar que cada notificação está assinada corretamente. É a opção mais segura.
  • Bearer Token: autenticação por token no cabeçalho da requisição.
  • Basic Auth: usuário e senha.
  • Sem autenticação: o endpoint recebe a notificação sem nenhuma validação adicional. Recomendável apenas se seu endpoint não for acessível publicamente ou você já o proteger de outra forma.

⚠️ Importante: com a Assinatura HMAC, a Acreditta assina cada notificação com uma Secret Key própria daquele webhook (você verá a assinatura no cabeçalho X-Hub-Signature-256 de cada requisição). Esse é o valor que seu backend precisa para validar a autenticidade de cada notificação — guarde-o em um lugar seguro.

Eventos disponíveis

Os eventos estão agrupados em dois blocos, e você pode marcar quantos precisar (ou usar “Marcar todos” em cada bloco):

Credenciais:
– Aceita
– Pendente
– Falhou
– Revogada
– Expirada
– Versionada

Emissões em lote:
– Iniciada — o lote de emissões começa o processamento.
– Concluída — o lote de emissões termina o processamento e informa o status dos envios.

Clique em Salvar Webhook para finalizar.

Depois de salvá-lo

O webhook aparece na lista com sua URL, o tipo de autenticação e os eventos inscritos:

🔎 Observação: o webhook é criado com status Inativo. Verifique esse status na lista antes de considerá-lo configurado.

A partir dos ícones dessa mesma linha você pode editar a configuração, testar o webhook, ativá-lo ou desativá-lo, e excluí-lo.

Testar o webhook

Antes de depender de um webhook em produção, você pode disparar uma notificação de teste para o seu endpoint pelo ícone correspondente na linha. A Acreditta mostra o detalhe completo da requisição enviada e da resposta recebida (ou o erro, se seu endpoint não respondeu):

  • URL do endpoint e UUID do webhook sendo testado.
  • Cabeçalhos (Headers) da requisição, incluindo a assinatura X-Hub-Signature-256 quando você usa Assinatura HMAC.
  • Corpo (Body) da requisição — por exemplo, para o evento “Pendente”:
{
  "scope": "credentials",
  "subscope": "status_pending",
  "timestamp": "2026-09-04T23:18:17.834069+00:00",
  "data": {
    "badge_uuid": "73b127b1-e913-40c4-abd7-3b85453d1d76",
    "new_status": "pending",
    "previous_status": "generating"
  }
}
  • Detalhe da resposta do seu servidor, ou a mensagem de erro caso não tenha sido possível se conectar (por exemplo, se o domínio não existir ou não responder).

🔎 Observação: esse teste é a forma mais rápida de confirmar que seu backend recebe e valida corretamente a assinatura antes de ativar o webhook de verdade.

Resiliência da entrega

Projete seu backend assumindo que uma notificação pode não chegar — por exemplo, se seu endpoint estiver fora do ar no momento exato em que o evento acontece. Não assuma que a Acreditta vai tentar novamente automaticamente uma entrega falha; se sua integração depende de não perder nenhum evento, complemente os webhooks com uma consulta periódica à API (por exemplo, /report/credential/status) para reconciliar o status real das suas credenciais.

🔎 Observação: se tiver dúvidas sobre o comportamento exato de novas tentativas para o seu caso, escreva para tech@acreditta.com antes de construir sua integração assumindo um número específico de tentativas.


CONTENIDO

Powered By EazyDocs