Webhooks

Statt zu pollen, lässt du Chess Scanner deine App benachrichtigen, sobald sich eine Partie eines Nutzers ändert. Du erhältst einen signierten HTTP-POST für diese Ereignisse:

• game.created
• game.updated
• game.deleted

Webhook einrichten

1. Öffne deine App unter Dashboard → OAuth-Apps → deine App.
2. Setze im Bereich Webhooks:
   • Payload-URL: wohin Zustellungen gesendet werden, zum Beispiel https://deine-app.de/webhooks/chess-scanner.
   • Ereignisse: welche der drei Ereignisse du empfangen willst.
   • Aktiv: Zustellung an- oder ausschalten.
3. Speichern. Ein Signatur-Secret wird erzeugt und einmalig angezeigt, also speichere es. Du brauchst es, um Zustellungen zu verifizieren.

Ein Webhook stellt Ereignisse für jeden Nutzer zu, der deine App mit dem Scope games.read autorisiert hat.

Payload

Zustellungen sind bewusst schlank. Sie sagen dir, was sich geändert hat, nicht die komplette Partie, also hole den aktuellen Stand über die API.

{
  "id": "evt_…",
  "type": "game.updated",
  "timestamp": "2026-06-14T10:00:00.000Z",
  "data": { "gameId": "…", "databaseId": "…" }
}

Jede Anfrage trägt diese Header:

Signatur verifizieren

Verifiziere die Signatur immer, bevor du einer Zustellung vertraust. Berechne den HMAC über den rohen Request-Body und vergleiche ihn in konstanter Zeit:

import { createHmac, timingSafeEqual } from "node:crypto";

export function isValid(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(signatureHeader ?? "");
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Antworte schnell mit einem 2xx-Status und erledige aufwändige Arbeit danach. Alles außer einem 2xx, ein Timeout oder ein Verbindungsfehler gilt als Fehlschlag und wird erneut versucht.

Zustellung & Zuverlässigkeit

• Mindestens einmal. Fehlgeschlagene Zustellungen werden mit exponentiellem Backoff bis zu einer Maximalzahl an Versuchen wiederholt und dann als fehlgeschlagen markiert. Mach deinen Handler idempotent, indem du über X-Webhook-Id deduplizierst.
• Die Reihenfolge ist nicht garantiert. Behandle jedes Ereignis als Signal, dass sich etwas geändert hat, und hole den aktuellen Stand, statt dich auf die Reihenfolge zu verlassen.
• Historie und erneut senden. Die Detailseite der App zeigt die letzten Zustellungen mit Status und lässt dich jede davon per Klick erneut senden.