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	Јединствени 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 испоруке (исти као 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) и престаје да прима испоруке док је не поправите и региструјете нову крајњу тачку.
• Испоруке могу стићи више пута. Користите ID X-Bws-Delivery (или id из тела) да бисте свој обрађивач учинили идемпотентним.
• Одговорите брзо (у року од ~10 секунди). Захтевне послове обавите асинхроно након потврде.

Управљање webhook-овима на контролној табли

Крајњим тачкама можете управљати и без API-ја — отворите Webhooks у бочној траци контролне табле да бисте додали, излистали и обрисали крајње тачке и изабрали које догађаје свака од њих прима.