Webhooks API

Webhook আপনার অ্যাপ্লিকেশনকে রিয়েল টাইমে জানিয়ে দেয় যখন আপনার ক্রেডেনশিয়ালে কিছু ঘটে — যখন একটি ইস্যু, ডেলিভার, রিভোক, বা ভিউ করা হয়। API পোল করার পরিবর্তে, আপনি একটি HTTPS এন্ডপয়েন্ট নিবন্ধন করেন এবং badges.ninja আপনি সাবস্ক্রাইব করা প্রতিটি ইভেন্টের জন্য এটিতে একটি স্বাক্ষরিত POST পাঠায়।

সমস্ত ম্যানেজমেন্ট এন্ডপয়েন্টের জন্য X-Api-Key হেডারের মাধ্যমে প্রমাণীকরণ প্রয়োজন। দেখুন প্রমাণীকরণ। এন্ডপয়েন্ট তৈরি বা মুছে ফেলার জন্য write স্কোপ সহ একটি কী প্রয়োজন; তালিকাভুক্ত করার জন্য read প্রয়োজন। দেখুন API কী।

একটি এন্ডপয়েন্ট নিবন্ধন করুন

POST /webhooks

প্যারামিটার

প্যারামিটার	টাইপ	প্রয়োজনীয়	বিবরণ
url	string	হ্যাঁ	আপনার HTTPS এন্ডপয়েন্ট। অবশ্যই https:// দিয়ে শুরু হতে হবে।
events	string[]	না	সাবস্ক্রাইব করার ইভেন্ট টাইপ। সব ইভেন্ট পেতে বাদ দিন বা ["*"] পাস করুন।

উদাহরণ

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

প্রতিক্রিয়া

201 Created। সাইনিং সিক্রেট শুধুমাত্র একবার ফেরত দেওয়া হয় — এখনই এটি সংরক্ষণ করুন; আপনি এটি আর পুনরুদ্ধার করতে পারবেন না।

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

এন্ডপয়েন্ট তালিকাভুক্ত করুন

GET /webhooks

আপনার নিবন্ধিত এন্ডপয়েন্টগুলি ফেরত দেয়। সাইনিং সিক্রেট কখনও অন্তর্ভুক্ত করা হয় না।

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

একটি এন্ডপয়েন্ট মুছে ফেলুন

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"

এন্ডপয়েন্টে ডেলিভারি অবিলম্বে বন্ধ হয়ে যায়।

ইভেন্ট টাইপ

ইভেন্ট	যখন ফায়ার করে…
credential.issued	একটি ক্রেডেনশিয়াল একজন প্রাপকের কাছে ইস্যু করা হয়।
credential.delivered	একটি ক্রেডেনশিয়ালের নোটিফিকেশন ইমেইল প্রাপকের কাছে পাঠানো হয় (একক বা বাল্ক)।
credential.revoked	একটি ক্রেডেনশিয়াল রিভোক করা হয়।
credential.viewed	একজন প্রাপকের সর্বজনীন ক্রেডেনশিয়াল পৃষ্ঠা প্রথমবারের জন্য ভিউ করা হয়।

ডেলিভারি পেলোড

প্রতিটি ডেলিভারি হল এই আকৃতির একটি JSON বডি সহ একটি POST:

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

ফিল্ড	বিবরণ
id	অনন্য ডেলিভারি id (ডি-ডুপ্লিকেট করতে এটি ব্যবহার করুন)।
type	ইভেন্ট টাইপ।
createdAt	ইভেন্ট টাইমস্ট্যাম্প (epoch মিলিসেকেন্ড)।
data	ইভেন্ট-নির্দিষ্ট পেলোড (নিচে দেখুন)।

ইভেন্ট টাইপ অনুযায়ী data

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

রিকোয়েস্ট হেডার

প্রতিটি ডেলিভারি এই হেডারগুলি বহন করে:

হেডার	বিবরণ
X-Bws-Event	ইভেন্ট টাইপ (বডিতে type এর মতোই)।
X-Bws-Delivery	ডেলিভারি id (বডিতে id এর মতোই)।
X-Bws-Signature	sha256= এর পরে কাঁচা রিকোয়েস্ট বডির HMAC-SHA256, আপনার এন্ডপয়েন্ট সিক্রেট দিয়ে কী করা।
User-Agent	badges.ninja-webhooks/1

স্বাক্ষর যাচাই করা

একটি ডেলিভারিকে বিশ্বাস করার আগে সবসময় স্বাক্ষর যাচাই করুন। আপনার এন্ডপয়েন্টের সাইনিং সিক্রেট ব্যবহার করে কাঁচা রিকোয়েস্ট বডির HMAC-SHA256 গণনা করুন, এবং এটিকে (কনস্ট্যান্ট টাইমে) 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);
}

আপনি যে সঠিক বাইটগুলি পেয়েছেন সেগুলি ব্যবহার করুন — প্রথমে JSON পার্স করে পুনরায় সিরিয়ালাইজ করলে বাইটগুলি পরিবর্তিত হবে এবং স্বাক্ষর ভেঙে যাবে।

পুনঃপ্রচেষ্টা ও নির্ভরযোগ্যতা

• একটি ডেলিভারি সফল বলে বিবেচিত হয় যখন আপনার এন্ডপয়েন্ট একটি 2xx স্ট্যাটাস সহ প্রতিক্রিয়া জানায়।
• ব্যর্থ ডেলিভারিগুলি অল্প কয়েকবার পুনঃচেষ্টা করা হয়। যে এন্ডপয়েন্টগুলি ক্রমাগত ব্যর্থ হতে থাকে সেগুলি একটি failureCount জমা করে; 20টি ধারাবাহিক ব্যর্থতার পরে একটি এন্ডপয়েন্ট স্বয়ংক্রিয়ভাবে নিষ্ক্রিয় করা হয় (active: false) এবং আপনি এটি ঠিক না করা ও একটি নতুন এন্ডপয়েন্ট নিবন্ধন না করা পর্যন্ত ডেলিভারি পাওয়া বন্ধ করে দেয়।
• ডেলিভারিগুলি একাধিকবার আসতে পারে। আপনার হ্যান্ডলারকে idempotent করতে X-Bws-Delivery id (বা বডির id) ব্যবহার করুন।
• দ্রুত প্রতিক্রিয়া জানান (~10 সেকেন্ডের মধ্যে)। স্বীকৃতি জানানোর পরে ভারী কাজ অ্যাসিঙ্ক্রোনাসভাবে করুন।

ড্যাশবোর্ডে Webhook পরিচালনা করা

আপনি API ছাড়াই এন্ডপয়েন্ট পরিচালনা করতে পারেন — এন্ডপয়েন্ট যোগ, তালিকাভুক্ত ও মুছে ফেলতে এবং প্রতিটি কোন ইভেন্ট গ্রহণ করে তা বেছে নিতে ড্যাশবোর্ড সাইডবারে Webhooks খুলুন।