Webhooks API

Webhooks, kimlik bilgilerinize bir şey olduğunda — biri verildiğinde, teslim edildiğinde, iptal edildiğinde veya görüntülendiğinde — uygulamanızı gerçek zamanlı olarak bilgilendirir. API'yi sürekli yoklamak yerine bir HTTPS uç noktası kaydedersiniz ve badges.ninja, abone olduğunuz her olay için ona imzalı bir POST gönderir.

Tüm yönetim uç noktaları X-Api-Key başlığı aracılığıyla kimlik doğrulaması gerektirir. Bkz. Kimlik Doğrulama. Uç nokta oluşturmak veya silmek write kapsamına sahip bir anahtar gerektirir; listeleme read gerektirir. Bkz. API Anahtarları.

Bir Uç Nokta Kaydetme

POST /webhooks

Parametreler

Parametre	Tür	Zorunlu	Açıklama
url	string	Evet	HTTPS uç noktanız. https:// ile başlamalıdır.
events	string[]	Hayır	Abone olunacak olay türleri. Tüm olayları almak için atlayın veya ["*"] geçin.

Örnek

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

Yanıt

201 Created. İmzalama gizli anahtarı yalnızca bir kez döndürülür — şimdi saklayın; onu bir daha alamazsınız.

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

Uç Noktaları Listeleme

GET /webhooks

Kayıtlı uç noktalarınızı döndürür. İmzalama gizli anahtarları asla dahil edilmez.

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

Bir Uç Noktayı Silme

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"

Uç noktaya teslimatlar hemen durur.

Olay Türleri

Olay	Şu durumda tetiklenir…
credential.issued	Bir alıcıya bir kimlik bilgisi verilir.
credential.delivered	Bir kimlik bilgisinin bildirim e-postası alıcıya gönderilir (tekli veya toplu).
credential.revoked	Bir kimlik bilgisi iptal edilir.
credential.viewed	Bir alıcının herkese açık kimlik bilgisi sayfası ilk kez görüntülenir.

Teslimat Yükü

Her teslimat, şu şekle sahip bir JSON gövdesiyle gönderilen bir POST'tur:

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

Alan	Açıklama
id	Benzersiz teslimat kimliği (yinelenenleri elemek için kullanın).
type	Olay türü.
createdAt	Olay zaman damgası (epoch milisaniye).
data	Olaya özgü yük (aşağıya bakın).

Olay türüne göre 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" }
}

İstek Başlıkları

Her teslimat şu başlıkları taşır:

Başlık	Açıklama
X-Bws-Event	Olay türü (gövdedeki type ile aynı).
X-Bws-Delivery	Teslimat kimliği (gövdedeki id ile aynı).
X-Bws-Signature	sha256= ve ardından ham istek gövdesinin, uç nokta gizli anahtarınızla anahtarlanmış HMAC-SHA256'sı.
User-Agent	badges.ninja-webhooks/1

İmzaları Doğrulama

Bir teslimata güvenmeden önce her zaman imzayı doğrulayın. Ham istek gövdesinin HMAC-SHA256'sını uç noktanızın imzalama gizli anahtarını kullanarak hesaplayın ve bunu (sabit zamanda) X-Bws-Signature başlığıyla karşılaştırın.

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

Aldığınız baytları tam olarak kullanın — JSON'u önce ayrıştırıp yeniden serileştirmek baytları değiştirir ve imzayı bozar.

Yeniden Denemeler ve Güvenilirlik

• Uç noktanız bir 2xx durumuyla yanıt verdiğinde bir teslimat başarılı sayılır.
• Başarısız teslimatlar kısa bir süre boyunca yeniden denenir. Sürekli başarısız olan uç noktalar bir failureCount biriktirir; 20 ardışık başarısızlıktan sonra bir uç nokta otomatik olarak devre dışı bırakılır (active: false) ve siz sorunu düzeltip yeni bir uç nokta kaydedene kadar teslimat almayı durdurur.
• Teslimatlar birden fazla kez ulaşabilir. İşleyicinizi bağımsız (idempotent) hale getirmek için X-Bws-Delivery kimliğini (veya gövdedeki id'yi) kullanın.
• Hızlı yanıt verin (~10 saniye içinde). Onayladıktan sonra ağır işleri asenkron olarak yapın.

Webhooks'u Kontrol Panelinden Yönetme

Uç noktaları API olmadan da yönetebilirsiniz — uç nokta eklemek, listelemek ve silmek ve her birinin hangi olayları alacağını seçmek için kontrol paneli kenar çubuğundaki Webhooks'u açın.