Webhooks API

Webhooks realiu laiku praneša jūsų programai, kai kažkas įvyksta su jūsų kredencialais — kai jis išduodamas, pristatomas, atšaukiamas ar peržiūrimas. Vietoj to, kad nuolat apklausinėtumėte API, jūs užregistruojate HTTPS galinį tašką, ir badges.ninja siunčia jam pasirašytą POST už kiekvieną įvykį, kurį užsiprenumeravote.

Visi valdymo galiniai taškai reikalauja autentikavimo per antraštę X-Api-Key. Žr. Autentikavimas. Galinių taškų kūrimas ar trynimas reikalauja rakto su rašymo sritimi; sąrašo peržiūra reikalauja skaitymo. Žr. API raktai.

Galinio taško registravimas

POST /webhooks

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
url	string	Taip	Jūsų HTTPS galinis taškas. Turi prasidėti https://.
events	string[]	Ne	Įvykių tipai, kuriuos norite užsiprenumeruoti. Praleiskite arba perduokite ["*"], kad gautumėte visus įvykius.

Pavyzdys

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

Atsakymas

201 Created. Pasirašymo slaptažodis grąžinamas tik vieną kartą — išsaugokite jį dabar; jo nebegalėsite gauti dar kartą.

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

Galinių taškų sąrašas

GET /webhooks

Grąžina jūsų užregistruotus galinius taškus. Pasirašymo slaptažodžiai niekada neįtraukiami.

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

Galinio taško ištrynimas

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"

Pristatymai į galinį tašką nedelsiant sustabdomi.

Įvykių tipai

Įvykis	Suveikia, kai…
credential.issued	Kredencialas išduodamas gavėjui.
credential.delivered	Kredencialo pranešimo el. laiškas išsiunčiamas gavėjui (pavienis ar masinis).
credential.revoked	Kredencialas atšaukiamas.
credential.viewed	Gavėjo viešas kredencialo puslapis peržiūrimas pirmą kartą.

Pristatymo turinys (payload)

Kiekvienas pristatymas yra POST su tokios formos JSON kūnu:

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

Laukas	Aprašymas
id	Unikalus pristatymo id (naudokite jį dubliavimui pašalinti).
type	Įvykio tipas.
createdAt	Įvykio laiko žyma (epocha milisekundėmis).
data	Įvykiui specifinis turinys (žr. žemiau).

data pagal įvykio tipą

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

Užklausos antraštės

Kiekvienas pristatymas turi šias antraštes:

Antraštė	Aprašymas
X-Bws-Event	Įvykio tipas (toks pat kaip type kūne).
X-Bws-Delivery	Pristatymo id (toks pat kaip id kūne).
X-Bws-Signature	sha256=, po kurio eina neapdoroto užklausos kūno HMAC-SHA256, pasirašytas jūsų galinio taško slaptažodžiu.
User-Agent	badges.ninja-webhooks/1

Parašų tikrinimas

Prieš pasitikėdami pristatymu, visada patikrinkite parašą. Apskaičiuokite neapdoroto užklausos kūno HMAC-SHA256, naudodami savo galinio taško pasirašymo slaptažodį, ir palyginkite jį (pastoviu laiku) su antrašte 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);
}

Naudokite tiksliai tuos baitus, kuriuos gavote — pirma išanalizavus ir iš naujo serializavus JSON, pasikeis baitai ir parašas nebegalios.

Pakartojimai ir patikimumas

• Pristatymas laikomas sėkmingu, kai jūsų galinis taškas atsako 2xx būsena.
• Nepavykę pristatymai kartojami keletą kartų. Nuolat nesėkmingi galiniai taškai kaupia failureCount; po 20 iš eilės einančių nesėkmių galinis taškas automatiškai išjungiamas (active: false) ir nebegauna pristatymų, kol jo nepataisysite ir neužregistruosite naujo galinio taško.
• Pristatymai gali atkeliauti daugiau nei vieną kartą. Naudokite X-Bws-Delivery id (arba kūno id), kad jūsų apdorojiklis būtų idempotentinis.
• Atsakykite greitai (per ~10 sekundžių). Sudėtingą darbą atlikite asinchroniškai po patvirtinimo.

Webhooks valdymas skydelyje

Galinius taškus taip pat galite valdyti ir be API — atidarykite Webhooks skydelio šoninėje juostoje, kad pridėtumėte, peržiūrėtumėte ir ištrintumėte galinius taškus bei pasirinktumėte, kokius įvykius kiekvienas iš jų gauna.