Webhooks API

Webhook memberi tahu aplikasi Anda secara real time ketika terjadi sesuatu pada kredensial Anda — ketika kredensial diterbitkan, dikirimkan, dicabut, atau dilihat. Alih-alih melakukan polling ke API, Anda mendaftarkan endpoint HTTPS dan badges.ninja mengirimkan POST bertanda tangan untuk setiap peristiwa yang Anda langgani.

Semua endpoint pengelolaan memerlukan autentikasi melalui tajuk X-Api-Key. Lihat Autentikasi. Membuat atau menghapus endpoint memerlukan kunci dengan cakupan write; menampilkan daftar memerlukan read. Lihat Kunci API.

Mendaftarkan Endpoint

POST /webhooks

Parameter

Parameter	Tipe	Wajib	Deskripsi
url	string	Ya	Endpoint HTTPS Anda. Harus diawali dengan https://.
events	string[]	Tidak	Tipe peristiwa yang akan dilanggani. Kosongkan atau berikan ["*"] 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. Rahasia penanda tangan hanya dikembalikan sekali — simpan sekarang; Anda tidak dapat mengambilnya lagi.

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

Menampilkan Daftar Endpoint

GET /webhooks

Mengembalikan endpoint terdaftar Anda. Rahasia penanda tangan 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
    }
  ]
}

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

Pengiriman ke endpoint tersebut berhenti seketika.

Tipe Peristiwa

Peristiwa	Terpicu ketika…
credential.issued	Sebuah kredensial diterbitkan kepada penerima.
credential.delivered	Email notifikasi kredensial dikirim kepada penerima (tunggal atau massal).
credential.revoked	Sebuah kredensial dicabut.
credential.viewed	Halaman kredensial publik seorang penerima dilihat untuk pertama kalinya.

Payload Pengiriman

Setiap pengiriman adalah POST dengan isi JSON berbentuk berikut:

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

Field	Deskripsi
id	Id pengiriman unik (gunakan untuk deduplikasi).
type	Tipe peristiwa.
createdAt	Stempel waktu peristiwa (epoch milidetik).
data	Payload spesifik peristiwa (lihat di bawah).

data berdasarkan tipe 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" }
}

Tajuk Permintaan

Setiap pengiriman membawa tajuk-tajuk berikut:

Tajuk	Deskripsi
X-Bws-Event	Tipe peristiwa (sama dengan type pada isi).
X-Bws-Delivery	Id pengiriman (sama dengan id pada isi).
X-Bws-Signature	sha256= diikuti oleh HMAC-SHA256 dari isi permintaan mentah, dengan kunci rahasia endpoint Anda.
User-Agent	badges.ninja-webhooks/1

Memverifikasi Tanda Tangan

Selalu verifikasi tanda tangan sebelum mempercayai suatu pengiriman. Hitung HMAC-SHA256 dari isi permintaan mentah menggunakan rahasia penanda tangan endpoint Anda, lalu bandingkan (dalam waktu konstan) dengan tajuk 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 byte persis seperti yang Anda terima — mem-parsing dan menserialisasi ulang JSON terlebih dahulu akan mengubah byte dan merusak tanda tangan.

Percobaan Ulang & Keandalan

• Suatu pengiriman dianggap berhasil ketika endpoint Anda merespons dengan status 2xx.
• Pengiriman yang gagal dicoba ulang beberapa kali secara terbatas. Endpoint yang terus gagal mengakumulasi failureCount; setelah 20 kegagalan berturut-turut, sebuah endpoint dinonaktifkan secara otomatis (active: false) dan berhenti menerima pengiriman hingga Anda memperbaikinya dan mendaftarkan endpoint baru.
• Pengiriman dapat tiba lebih dari sekali. Gunakan id X-Bws-Delivery (atau id pada isi) untuk membuat handler Anda idempoten.
• Respons dengan cepat (dalam ~10 detik). Lakukan pekerjaan berat secara asinkron setelah memberikan konfirmasi.

Mengelola Webhook di Dasbor

Anda juga dapat mengelola endpoint tanpa API — buka Webhooks di bilah sisi dasbor untuk menambahkan, menampilkan daftar, dan menghapus endpoint serta memilih peristiwa mana yang diterima masing-masing.