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 à API, regista um endpoint HTTPS e o badges.ninja envia-lhe um POST assinado para cada evento que subscrever.

Todos os endpoints de gestão exigem autenticação através do cabeçalho X-Api-Key. Consulte Autenticação. Criar ou eliminar endpoints exige uma chave com âmbito de escrita; listar exige leitura. Consulte Chaves de API.

Registar um endpoint

POST /webhooks

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
url	string	Sim	O seu endpoint HTTPS. Deve começar por https://.
events	string[]	Não	Tipos de evento a subscrever. 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 é devolvido apenas uma vez — guarde-o agora; não o poderá recuperar novamente.

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

Listar endpoints

GET /webhooks

Devolve os seus endpoints registados. 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
    }
  ]
}

Eliminar 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 de imediato.

Tipos de evento

Evento	Dispara quando…
credential.issued	Uma credencial é emitida a 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 com este formato:

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

Campo	Descrição
id	Id único da entrega (utilize-o para eliminar duplicados).
type	O tipo de evento.
createdAt	Data/hora do evento (milissegundos epoch).
data	Payload específico do evento (ver 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 do pedido

Cada entrega inclui 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 do pedido, com chave no segredo do seu endpoint.
User-Agent	badges.ninja-webhooks/1

Verificar assinaturas

Verifique sempre a assinatura antes de confiar numa entrega. Calcule o HMAC-SHA256 do corpo bruto do pedido 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);
}

Utilize exatamente os bytes que recebeu — analisar e voltar a serializar o JSON antes mudará os bytes e quebrará a assinatura.

Retentativas e fiabilidade

• Uma entrega é considerada bem-sucedida quando o seu endpoint responde com um estado 2xx.
• As entregas falhadas são repetidas um pequeno número de vezes. Os endpoints que continuam a falhar acumulam um failureCount; após 20 falhas consecutivas, um endpoint é desativado automaticamente (active: false) e deixa de receber entregas até que o corrija e registe um novo endpoint.
• As entregas podem chegar mais do que uma vez. Utilize o id X-Bws-Delivery (ou o id do corpo) para tornar o seu manipulador idempotente.
• Responda com rapidez (em cerca de ~10 segundos). Faça o trabalho pesado de forma assíncrona depois de confirmar a receção.

Gerir webhooks no painel

Também pode gerir os endpoints sem a API — abra Webhooks na barra lateral do painel para adicionar, listar e eliminar endpoints e escolher que eventos cada um recebe.