Webhooks API

Вебхуки сповіщають ваш застосунок у реальному часі про події, що відбуваються з вашими обліковими даними, — коли їх видано, доставлено, відкликано чи переглянуто. Замість опитування API ви реєструєте HTTPS-ендпоінт, і badges.ninja надсилає на нього підписаний POST для кожної події, на яку ви підписані.

Усі керуючі ендпоінти вимагають автентифікації через заголовок X-Api-Key. Див. Автентифікація. Створення або видалення ендпоінтів вимагає ключа з областю доступу write; для отримання списку потрібна read. Див. Ключі 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	Позначка часу події (мілісекунди епохи).
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 секунд). Виконуйте важку роботу асинхронно після підтвердження.

Керування вебхуками в панелі

Ви також можете керувати ендпоінтами без API — відкрийте Webhooks у бічному меню панелі, щоб додавати, переглядати й видаляти ендпоінти та обирати, які події отримує кожен із них.