Webhooks API

Webhook-овете уведомяват приложението ви в реално време, когато нещо се случи с вашите удостоверения — когато някое бъде издадено, доставено, отменено или прегледано. Вместо да опитвате API, регистрирате HTTPS крайна точка и badges.ninja ѝ изпраща подписан POST за всяко събитие, за което сте се абонирали.

Всички крайни точки за управление изискват удостоверяване чрез хедъра X-Api-Key. Вижте Удостоверяване. Създаването или изтриването на крайни точки изисква ключ с обхват на запис; извеждането на списък изисква четене. Вижте API ключове.

Регистриране на крайна точка

POST /webhooks

Параметри

Параметър	Тип	Задължителен	Описание
url	string	Да	Вашата HTTPS крайна точка. Трябва да започва с https://.
events	string[]	Не	Типовете събития, за които се абонирате. Пропуснете или подайте ["*"], за да получавате всички събития.

Пример

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"]
  }'

Отговор

201 Created. Тайният ключ за подписване се връща само веднъж — съхранете го сега; не можете да го извлечете отново.

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

Извеждане на крайни точки

GET /webhooks

Връща регистрираните ви крайни точки. Тайните ключове за подписване никога не се включват.

{
  "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
    }
  ]
}

Изтриване на крайна точка

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"

Доставките към крайната точка спират незабавно.

Типове събития

Събитие	Задейства се, когато…
credential.issued	Удостоверение е издадено на получател.
credential.delivered	Имейлът за известяване на удостоверение е изпратен на получателя (единично или групово).
credential.revoked	Удостоверение е отменено.
credential.viewed	Публичната страница на удостоверение на получател е прегледана за първи път.

Съдържание на доставката

Всяка доставка е POST с JSON тяло със следната форма:

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

Поле	Описание
id	Уникален идентификатор на доставката (използвайте го за дедупликация).
type	Типът на събитието.
createdAt	Времеви печат на събитието (epoch милисекунди).
data	Съдържание, специфично за събитието (вижте по-долу).

data според типа на събитието

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" }
}

Хедъри на заявката

Всяка доставка носи тези хедъри:

Хедър	Описание
X-Bws-Event	Типът на събитието (същият като type в тялото).
X-Bws-Delivery	Идентификаторът на доставката (същият като id в тялото).
X-Bws-Signature	sha256=, следван от HMAC-SHA256 на суровото тяло на заявката, с ключ тайния ключ на вашата крайна точка.
User-Agent	badges.ninja-webhooks/1

Проверка на подписите

Винаги проверявайте подписа, преди да се доверите на доставка. Изчислете HMAC-SHA256 на суровото тяло на заявката, използвайки тайния ключ за подписване на вашата крайна точка, и го сравнете (в постоянно време) с хедъра 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);
}

Използвайте точно байтовете, които сте получили — предварителното парсиране и повторно сериализиране на JSON ще промени байтовете и ще наруши подписа.

Повторни опити и надеждност

• Доставката се счита за успешна, когато вашата крайна точка отговори със статус 2xx.
• Неуспешните доставки се повтарят малък брой пъти. Крайните точки, които продължават да се провалят, натрупват failureCount; след 20 последователни неуспеха крайната точка се деактивира автоматично (active: false) и спира да получава доставки, докато не я поправите и регистрирате нова крайна точка.
• Доставките могат да пристигнат повече от веднъж. Използвайте идентификатора X-Bws-Delivery (или id от тялото), за да направите вашия обработчик идемпотентен.
• Отговаряйте бързо (в рамките на ~10 секунди). Извършвайте тежката работа асинхронно след потвърждаване.

Управление на webhook-ове в таблото

Можете да управлявате крайни точки и без API — отворете Webhooks в страничната лента на таблото, за да добавяте, извеждате и изтривате крайни точки и да избирате кои събития получава всяка от тях.