Webhooks API

Webhooks आपके एप्लिकेशन को वास्तविक समय में सूचित करते हैं जब आपके क्रेडेंशियल के साथ कुछ घटित होता है — जब कोई जारी, वितरित, निरस्त, या देखा जाता है। 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) कर दिया जाता है और तब तक वितरण प्राप्त करना बंद कर देता है जब तक आप इसे ठीक नहीं करते और एक नया एंडपॉइंट पंजीकृत नहीं करते।
• वितरण एक से अधिक बार आ सकते हैं। अपने हैंडलर को आइडेमपोटेंट बनाने के लिए X-Bws-Delivery id (या बॉडी id) का उपयोग करें।
• शीघ्रता से प्रतिक्रिया दें (~10 सेकंड के भीतर)। स्वीकार करने के बाद भारी कार्य अतुल्यकालिक रूप से करें।

डैशबोर्ड में Webhooks प्रबंधित करना

आप API के बिना भी एंडपॉइंट प्रबंधित कर सकते हैं — एंडपॉइंट जोड़ने, सूचीबद्ध करने और हटाने और यह चुनने के लिए कि प्रत्येक कौन से इवेंट प्राप्त करता है, डैशबोर्ड साइडबार में Webhooks खोलें।