Webhooks API

Webhooks reāllaikā paziņo jūsu lietojumprogrammai, kad ar jūsu akreditācijas datiem kaut kas notiek — kad tie tiek izsniegti, piegādāti, atsaukti vai apskatīti. Tā vietā, lai pastāvīgi aptaujātu API, jūs reģistrējat HTTPS galapunktu, un badges.ninja tam nosūta parakstītu POST pieprasījumu par katru notikumu, uz kuru esat abonējis.

Visiem pārvaldības galapunktiem nepieciešama autentifikācija ar galveni X-Api-Key. Skatiet Autentifikācija. Galapunktu izveidei vai dzēšanai nepieciešama atslēga ar rakstīšanas tvērumu; sarakstu skatīšanai — lasīšanas. Skatiet API atslēgas.

Galapunkta reģistrēšana

POST /webhooks

Parametri

Parametrs	Tips	Obligāts	Apraksts
url	string	Jā	Jūsu HTTPS galapunkts. Jāsākas ar https://.
events	string[]	Nē	Notikumu tipi, uz kuriem abonēt. Izlaidiet vai norādiet ["*"], lai saņemtu visus notikumus.

Piemērs

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

Atbilde

201 Created. Parakstīšanas noslēpums tiek atgriezts tikai vienu reizi — saglabājiet to tagad; jūs to vairs nevarēsiet iegūt.

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

Galapunktu saraksts

GET /webhooks

Atgriež jūsu reģistrētos galapunktus. Parakstīšanas noslēpumi nekad netiek iekļauti.

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

Galapunkta dzēšana

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"

Piegādes uz galapunktu tiek nekavējoties apturētas.

Notikumu tipi

Notikums	Nostrādā, kad…
credential.issued	Akreditācijas dati tiek izsniegti saņēmējam.
credential.delivered	Akreditācijas datu paziņojuma e-pasts tiek nosūtīts saņēmējam (atsevišķi vai masveidā).
credential.revoked	Akreditācijas dati tiek atsaukti.
credential.viewed	Saņēmēja publiskā akreditācijas datu lapa tiek apskatīta pirmo reizi.

Piegādes slodze

Katra piegāde ir POST pieprasījums ar šādas formas JSON pamattekstu:

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

Lauks	Apraksts
id	Unikāls piegādes id (izmantojiet to dublikātu novēršanai).
type	Notikuma tips.
createdAt	Notikuma laikspiedols (epohas milisekundes).
data	Notikumam specifiskā slodze (skatiet zemāk).

data pēc notikuma tipa

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

Pieprasījuma galvenes

Katra piegāde satur šādas galvenes:

Galvene	Apraksts
X-Bws-Event	Notikuma tips (tāds pats kā type pamattekstā).
X-Bws-Delivery	Piegādes id (tāds pats kā id pamattekstā).
X-Bws-Signature	sha256=, kam seko neapstrādātā pieprasījuma pamatteksta HMAC-SHA256, atslēgots ar jūsu galapunkta noslēpumu.
User-Agent	badges.ninja-webhooks/1

Parakstu pārbaude

Vienmēr pārbaudiet parakstu, pirms uzticaties piegādei. Aprēķiniet neapstrādātā pieprasījuma pamatteksta HMAC-SHA256, izmantojot jūsu galapunkta parakstīšanas noslēpumu, un salīdziniet to (nemainīgā laikā) ar galveni 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);
}

Izmantojiet tieši tos baitus, kurus saņēmāt — JSON parsēšana un atkārtota serializēšana mainīs baitus un sabojās parakstu.

Atkārtoti mēģinājumi un uzticamība

• Piegāde tiek uzskatīta par veiksmīgu, kad jūsu galapunkts atbild ar 2xx statusu.
• Neizdevušās piegādes tiek atkārtotas nelielu skaitu reižu. Galapunkti, kas turpina neizdoties, uzkrāj failureCount; pēc 20 secīgām neizdošanās reizēm galapunkts tiek automātiski atspējots (active: false) un pārstāj saņemt piegādes, līdz jūs to izlabosiet un reģistrēsiet jaunu galapunktu.
• Piegādes var pienākt vairāk nekā vienu reizi. Izmantojiet X-Bws-Delivery id (vai pamatteksta id), lai padarītu savu apstrādātāju idempotentu.
• Atbildiet ātri (aptuveni 10 sekunžu laikā). Smago darbu veiciet asinhroni pēc apstiprināšanas.

Webhooks pārvaldība vadības panelī

Galapunktus varat pārvaldīt arī bez API — atveriet Webhooks vadības paneļa sānjoslā, lai pievienotu, uzskaitītu un dzēstu galapunktus un izvēlētos, kurus notikumus katrs no tiem saņem.