Webhookien API

Webhookit ilmoittavat sovelluksellesi reaaliajassa, kun todistuksillesi tapahtuu jotain — kun todistus myönnetään, toimitetaan, peruutetaan tai katsotaan. Sen sijaan, että kyselisit API:a, rekisteröit HTTPS-päätepisteen, ja badges.ninja lähettää sille allekirjoitetun POST-pyynnön jokaisesta tapahtumasta, jota tilaat.

Kaikki hallintapäätepisteet vaativat todennuksen X-Api-Key-otsikon kautta. Katso Todennus. Päätepisteiden luominen tai poistaminen vaatii avaimen, jolla on write-alue; luettelointi vaatii read-alueen. Katso API-avaimet.

Rekisteröi päätepiste

POST /webhooks

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
url	string	Kyllä	HTTPS-päätepisteesi. Sen on alettava merkkijonolla https://.
events	string[]	Ei	Tilattavat tapahtumatyypit. Jätä pois tai anna ["*"] vastaanottaaksesi kaikki tapahtumat.

Esimerkki

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

Vastaus

201 Created. Allekirjoitussalaisuus palautetaan vain kerran — tallenna se nyt; et voi hakea sitä uudelleen.

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

Luettele päätepisteet

GET /webhooks

Palauttaa rekisteröidyt päätepisteesi. Allekirjoitussalaisuuksia ei koskaan sisällytetä.

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

Poista päätepiste

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"

Toimitukset päätepisteeseen pysähtyvät välittömästi.

Tapahtumatyypit

Tapahtuma	Laukeaa, kun…
credential.issued	Todistus myönnetään vastaanottajalle.
credential.delivered	Todistuksen ilmoitussähköposti lähetetään vastaanottajalle (yksittäin tai joukkona).
credential.revoked	Todistus peruutetaan.
credential.viewed	Vastaanottajan julkinen todistussivu katsotaan ensimmäistä kertaa.

Toimituksen hyötykuorma

Jokainen toimitus on POST, jonka JSON-runko on tätä muotoa:

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

Kenttä	Kuvaus
id	Yksilöllinen toimitustunnus (käytä sitä kaksoiskappaleiden poistamiseen).
type	Tapahtumatyyppi.
createdAt	Tapahtuman aikaleima (epoch-millisekuntia).
data	Tapahtumakohtainen hyötykuorma (katso alla).

data tapahtumatyypin mukaan

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

Pyynnön otsikot

Jokainen toimitus sisältää nämä otsikot:

Otsikko	Kuvaus
X-Bws-Event	Tapahtumatyyppi (sama kuin type rungossa).
X-Bws-Delivery	Toimitustunnus (sama kuin id rungossa).
X-Bws-Signature	sha256= ja sen perässä raa'an pyyntörungon HMAC-SHA256, avaimena päätepistesalaisuutesi.
User-Agent	badges.ninja-webhooks/1

Allekirjoitusten vahvistaminen

Vahvista allekirjoitus aina ennen kuin luotat toimitukseen. Laske raa'an pyyntörungon HMAC-SHA256 päätepisteesi allekirjoitussalaisuudella ja vertaa sitä (vakioajassa) X-Bws-Signature-otsikkoon.

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

Käytä täsmälleen niitä tavuja, jotka vastaanotit — JSON:n jäsentäminen ja uudelleensarjallistaminen ensin muuttaa tavuja ja rikkoo allekirjoituksen.

Uudelleenyritykset ja luotettavuus

• Toimitusta pidetään onnistuneena, kun päätepisteesi vastaa 2xx-tilalla.
• Epäonnistuneet toimitukset yritetään uudelleen muutaman kerran. Päätepisteet, jotka jatkavat epäonnistumista, kartuttavat failureCount-arvoa; 20 peräkkäisen epäonnistumisen jälkeen päätepiste poistetaan automaattisesti käytöstä (active: false) ja lakkaa vastaanottamasta toimituksia, kunnes korjaat sen ja rekisteröit uuden päätepisteen.
• Toimitukset voivat saapua useammin kuin kerran. Käytä X-Bws-Delivery-tunnusta (tai rungon id-arvoa) tehdäksesi käsittelijästäsi idempotentin.
• Vastaa nopeasti (noin 10 sekunnin kuluessa). Tee raskas työ asynkronisesti kuittauksen jälkeen.

Webhookien hallinta koontinäytöllä

Voit myös hallita päätepisteitä ilman API:a — avaa Webhooks koontinäytön sivupalkista lisätäksesi, luetellaksesi ja poistaaksesi päätepisteitä sekä valitaksesi, mitä tapahtumia kukin vastaanottaa.