API de Webhooks

Os webhooks notificam a sua aplicação em tempo real quando algo acontece com as suas credenciais — quando uma é emitida, entregue, revogada ou visualizada. Em vez de fazer polling na API, você registra um endpoint HTTPS e o badges.ninja envia a ele um POST assinado para cada evento que você assinar.

Todos os endpoints de gestão exigem autenticação por meio do cabeçalho X-Api-Key. Consulte Autenticação. Criar ou excluir endpoints exige uma chave com escopo de escrita; listar exige leitura. Consulte Chaves de API.

Registrar um endpoint

POST /webhooks

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
url	string	Sim	O seu endpoint HTTPS. Deve começar com https://.
events	string[]	Não	Tipos de evento a assinar. Omita ou passe ["*"] para receber todos os eventos.

Exemplo

curl -X POST https://api.badges.ninja/webhooks \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/badges",
    "events": ["credential.issued", "credential.delivered"]
  }'

Resposta

201 Created. O segredo de assinatura é retornado apenas uma vez — armazene-o agora; você não poderá recuperá-lo novamente.

{
  "id": "e4b19ff5-063d-4799-bd75-d03641be624f",
  "url": "https://example.com/hooks/badges",
  "events": ["credential.issued", "credential.delivered"],
  "secret": "2be6d335682c1658242fde3a523fd8a2493bab8c"
}

Listar endpoints

GET /webhooks

Retorna os seus endpoints registrados. Os segredos de assinatura nunca são incluídos.

{
  "webhooks": [
    {
      "id": "e4b19ff5-063d-4799-bd75-d03641be624f",
      "url": "https://example.com/hooks/badges",
      "events": ["credential.issued", "credential.delivered"],
      "active": true,
      "failureCount": 0,
      "createdAt": 1787685415083,
      "lastStatus": 200,
      "lastDeliveryAt": 1787685480777
    }
  ]
}

Excluir um endpoint

DELETE /webhooks/{id}

curl -X DELETE https://api.badges.ninja/webhooks/e4b19ff5-063d-4799-bd75-d03641be624f \
  -H "X-Api-Key: bws_your_api_key_here"

As entregas ao endpoint param imediatamente.

Tipos de evento

Evento	Dispara quando…
credential.issued	Uma credencial é emitida para um destinatário.
credential.delivered	O e-mail de notificação de uma credencial é enviado ao destinatário (individual ou em massa).
credential.revoked	Uma credencial é revogada.
credential.viewed	A página pública da credencial de um destinatário é visualizada pela primeira vez.

Corpo da entrega (payload)

Cada entrega é um POST com um corpo JSON neste formato:

{
  "id": "b1c2d3e4-...",
  "type": "credential.issued",
  "createdAt": 1787685415083,
  "data": { }
}

Campo	Descrição
id	Id único da entrega (use-o para eliminar duplicatas).
type	O tipo de evento.
createdAt	Carimbo de data/hora do evento (milissegundos epoch).
data	Payload específico do evento (veja abaixo).

data por tipo de evento

credential.issued

{
  "awardId": "https://api.badges.ninja/certify-badge/award/<guid>",
  "badgeId": "https://api.badges.ninja/certify-badge/badge/<guid>",
  "badgeName": "Advanced Certification",
  "recipient": { "email": "jane@example.com", "name": "Jane Doe" },
  "issuedOn": "2026-08-25",
  "expires": null
}

credential.delivered

{
  "awardId": "https://api.badges.ninja/certify-badge/award/<guid>",
  "recipient": { "email": "jane@example.com", "name": "Jane Doe" },
  "badgeName": "Advanced Certification"
}

credential.revoked

{ "awardId": "https://api.badges.ninja/certify-badge/award/<guid>", "reason": "Issued in error" }

credential.viewed

{
  "awardId": "https://api.badges.ninja/certify-badge/award/<guid>",
  "recipient": { "email": "jane@example.com", "name": "Jane Doe" }
}

Cabeçalhos da requisição

Cada entrega carrega estes cabeçalhos:

Cabeçalho	Descrição
X-Bws-Event	O tipo de evento (igual a type no corpo).
X-Bws-Delivery	O id da entrega (igual a id no corpo).
X-Bws-Signature	sha256= seguido do HMAC-SHA256 do corpo bruto da requisição, com chave no segredo do seu endpoint.
User-Agent	badges.ninja-webhooks/1

Verificando assinaturas

Sempre verifique a assinatura antes de confiar em uma entrega. Calcule o HMAC-SHA256 do corpo bruto da requisição usando o segredo de assinatura do seu endpoint e compare-o (em tempo constante) com o cabeçalho X-Bws-Signature.

import crypto from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Use exatamente os bytes que você recebeu — analisar e reserializar o JSON antes mudará os bytes e quebrará a assinatura.

Retentativas e confiabilidade

• Uma entrega é considerada bem-sucedida quando o seu endpoint responde com um status 2xx.
• Entregas com falha são retentadas um pequeno número de vezes. Endpoints que continuam falhando acumulam um failureCount; após 20 falhas consecutivas, um endpoint é desativado automaticamente (active: false) e para de receber entregas até que você o corrija e registre um novo endpoint.
• As entregas podem chegar mais de uma vez. Use o id X-Bws-Delivery (ou o id do corpo) para tornar o seu manipulador idempotente.
• Responda rapidamente (em cerca de ~10 segundos). Faça o trabalho pesado de forma assíncrona após confirmar o recebimento.

Gerenciando webhooks no painel

Você também pode gerenciar endpoints sem a API — abra Webhooks na barra lateral do painel para adicionar, listar e excluir endpoints e escolher quais eventos cada um recebe.