Webhooks API

Webhooks memberitahu aplikasi anda secara masa nyata apabila sesuatu berlaku kepada kredensial anda — apabila satu kredensial dikeluarkan, dihantar, dibatalkan atau dilihat. Daripada meninjau (poll) API, anda mendaftarkan titik akhir HTTPS dan badges.ninja menghantar POST yang ditandatangani kepadanya bagi setiap peristiwa yang anda langgani.

Semua titik akhir pengurusan memerlukan pengesahan melalui pengepala X-Api-Key. Lihat Pengesahan. Mencipta atau memadam titik akhir memerlukan kunci dengan skop write; menyenaraikan memerlukan read. Lihat Kunci API.

Mendaftarkan Titik Akhir

POST /webhooks

Parameter

Parameter	Jenis	Diperlukan	Penerangan
url	string	Ya	Titik akhir HTTPS anda. Mesti bermula dengan https://.
events	string[]	Tidak	Jenis peristiwa untuk dilanggani. Tinggalkan atau hantar ["*"] untuk menerima semua peristiwa.

Contoh

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

Respons

201 Created. Rahsia penandatanganan dikembalikan sekali sahaja — simpannya sekarang; anda tidak boleh mendapatkannya semula.

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

Menyenaraikan Titik Akhir

GET /webhooks

Mengembalikan titik akhir yang telah anda daftarkan. Rahsia penandatanganan tidak pernah disertakan.

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

Memadam Titik Akhir

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"

Penghantaran ke titik akhir berhenti serta-merta.

Jenis Peristiwa

Peristiwa	Berlaku apabila…
credential.issued	Satu kredensial dikeluarkan kepada penerima.
credential.delivered	E-mel pemberitahuan kredensial dihantar kepada penerima (tunggal atau pukal).
credential.revoked	Satu kredensial dibatalkan.
credential.viewed	Halaman kredensial awam penerima dilihat buat kali pertama.

Muatan Penghantaran

Setiap penghantaran ialah POST dengan badan JSON berbentuk ini:

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

Medan	Penerangan
id	ID penghantaran unik (gunakannya untuk menyahduplikat).
type	Jenis peristiwa.
createdAt	Cap masa peristiwa (milisaat epoch).
data	Muatan khusus peristiwa (lihat di bawah).

data mengikut jenis peristiwa

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

Pengepala Permintaan

Setiap penghantaran membawa pengepala berikut:

Pengepala	Penerangan
X-Bws-Event	Jenis peristiwa (sama seperti type dalam badan).
X-Bws-Delivery	ID penghantaran (sama seperti id dalam badan).
X-Bws-Signature	sha256= diikuti dengan HMAC-SHA256 bagi badan permintaan mentah, berkunci dengan rahsia titik akhir anda.
User-Agent	badges.ninja-webhooks/1

Mengesahkan Tandatangan

Sentiasa sahkan tandatangan sebelum mempercayai sesuatu penghantaran. Kira HMAC-SHA256 bagi badan permintaan mentah menggunakan rahsia penandatanganan titik akhir anda, dan bandingkannya (dalam masa malar) dengan pengepala 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);
}

Gunakan bait tepat yang anda terima — menghurai dan menyiri semula JSON terlebih dahulu akan mengubah bait dan merosakkan tandatangan.

Cubaan Semula & Kebolehpercayaan

• Sesuatu penghantaran dianggap berjaya apabila titik akhir anda membalas dengan status 2xx.
• Penghantaran yang gagal dicuba semula beberapa kali sahaja. Titik akhir yang terus gagal mengumpul failureCount; selepas 20 kegagalan berturut-turut, sesuatu titik akhir dilumpuhkan secara automatik (active: false) dan berhenti menerima penghantaran sehingga anda membaikinya dan mendaftarkan titik akhir baharu.
• Penghantaran boleh tiba lebih daripada sekali. Gunakan ID X-Bws-Delivery (atau id badan) untuk menjadikan pengendali anda idempoten.
• Balas dengan cepat (dalam ~10 saat). Lakukan kerja berat secara tak segerak selepas mengakui penerimaan.

Mengurus Webhooks dalam Papan Pemuka

Anda juga boleh mengurus titik akhir tanpa API — buka Webhooks dalam bar sisi papan pemuka untuk menambah, menyenarai dan memadam titik akhir serta memilih peristiwa yang setiap satu terima.