Webhooks API

Ang mga webhook ay nag-aabiso sa inyong aplikasyon sa real time kapag may nangyari sa inyong mga credential — kapag isang credential ay na-isyu, na-deliver, na-revoke, o na-view. Sa halip na i-poll ang API, magrerehistro kayo ng HTTPS endpoint at magpapadala rito ang badges.ninja ng naka-sign na POST para sa bawat event na sino-subscribe-an ninyo.

Ang lahat ng management endpoint ay nangangailangan ng authentication sa pamamagitan ng X-Api-Key header. Tingnan ang Authentication. Ang paggawa o pagbura ng mga endpoint ay nangangailangan ng key na may write scope; ang paglilista ay nangangailangan ng read. Tingnan ang Mga API Key.

Magrehistro ng Endpoint

POST /webhooks

Mga Parameter

Parameter	Type	Kailangan	Paglalarawan
url	string	Oo	Ang inyong HTTPS endpoint. Kailangang magsimula sa https://.
events	string[]	Hindi	Mga uri ng event na sino-subscribe-an. Alisin o ipasa ang ["*"] para matanggap ang lahat ng event.

Halimbawa

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

Response

201 Created. Ang signing secret ay ibinabalik nang isang beses lang — itago ito ngayon; hindi na ninyo ito makukuha muli.

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

Ilista ang mga Endpoint

GET /webhooks

Ibinabalik ang inyong mga narehistrong endpoint. Ang mga signing secret ay hindi kailanman isinasama.

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

Magbura ng Endpoint

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"

Agad na hihinto ang mga delivery sa endpoint.

Mga Uri ng Event

Event	Nagti-trigger kapag…
credential.issued	May credential na inisyu sa isang recipient.
credential.delivered	Naipadala ang notification email ng isang credential sa recipient (isahan o bulk).
credential.revoked	May credential na na-revoke.
credential.viewed	Ang public credential page ng isang recipient ay na-view sa unang beses.

Delivery Payload

Ang bawat delivery ay isang POST na may JSON body na may ganitong anyo:

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

Field	Paglalarawan
id	Natatanging delivery id (gamitin ito para mag-de-duplicate).
type	Ang uri ng event.
createdAt	Timestamp ng event (epoch milliseconds).
data	Payload na tukoy sa event (tingnan sa ibaba).

data ayon sa uri ng event

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

Mga Request Header

Ang bawat delivery ay may dalang mga header na ito:

Header	Paglalarawan
X-Bws-Event	Ang uri ng event (kapareho ng type sa body).
X-Bws-Delivery	Ang delivery id (kapareho ng id sa body).
X-Bws-Signature	sha256= na sinusundan ng HMAC-SHA256 ng raw request body, naka-key gamit ang inyong endpoint secret.
User-Agent	badges.ninja-webhooks/1

Pag-verify ng mga Signature

Palaging i-verify ang signature bago magtiwala sa isang delivery. Kalkulahin ang HMAC-SHA256 ng raw request body gamit ang signing secret ng inyong endpoint, at ihambing ito (sa constant time) sa X-Bws-Signature header.

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);
}

Gamitin ang eksaktong bytes na natanggap ninyo — ang pag-parse at pag-re-serialize muli ng JSON ay magbabago sa bytes at masisira ang signature.

Mga Retry at Pagiging Maaasahan

• Itinuturing na matagumpay ang isang delivery kapag ang inyong endpoint ay tumugon ng 2xx status.
• Ang mga nabigong delivery ay iniuulit nang ilang beses. Ang mga endpoint na patuloy na nabibigo ay nag-iipon ng failureCount; pagkatapos ng 20 magkakasunod na pagkabigo ang isang endpoint ay awtomatikong dini-disable (active: false) at hihinto sa pagtanggap ng mga delivery hanggang sa maayos ninyo ito at magrehistro ng bagong endpoint.
• Ang mga delivery ay maaaring dumating nang higit sa isang beses. Gamitin ang X-Bws-Delivery id (o ang body id) para gawing idempotent ang inyong handler.
• Tumugon agad (sa loob ng ~10 segundo). Gawin ang mabibigat na trabaho nang asynchronous pagkatapos mag-acknowledge.

Pamamahala ng mga Webhook sa Dashboard

Maaari rin ninyong pamahalaan ang mga endpoint nang walang API — buksan ang Webhooks sa dashboard sidebar para magdagdag, maglista, at magbura ng mga endpoint at piliin kung aling mga event ang tatanggapin ng bawat isa.