Webhooks

Übergeben Sie callback_url in POST /edits. Erreicht der Job succeeded oder failed, senden wir per POST dasselbe JSON an diese URL, das Sie von GET /edits/{id} erhalten würden.

• callback_url muss eine https-URL sein. Ihr Query-String bleibt erhalten, Sie können also eine eigene Referenz anhängen, etwa https://example.com/hooks/rewords?order=1234.
• Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status, um den Empfang zu bestätigen. Alles andere – ein anderer Status, ein Timeout, ein Verbindungsfehler – gilt als fehlgeschlagen.
• Eine fehlgeschlagene Zustellung wird 1, 5 und 30 Minuten nach dem vorherigen Versuch wiederholt, der letzte Versuch kommt also etwa 36 Minuten nach dem ersten. Danach hören wir auf; GET /edits/{id} liefert das Ergebnis weiterhin.
• Jede Wiederholung sendet dieselben Bytes mit derselben Signatur. Wegen der Wiederholungen können Sie denselben Job mehrmals erhalten: Nutzen Sie die id der Bearbeitung, um bereits verarbeitete zu ignorieren.
• Jede Zustellung ist signiert: X-Rewords-Signature: sha256=<64 Hex-Zeichen>, ein HMAC-SHA256 des unveränderten Request-Bodys mit Ihrem Webhook-Secret. Verwenden Sie den ganzen Secret-String einschließlich des Präfixes whsec_ als HMAC-Schlüssel.

Ihr Webhook-SecretCopy Anchor Link

Es gibt ein Webhook-Secret pro Konto, das sich alle seine Schlüssel teilen. Sie finden es auf Ihrer Seite mit den API-Schlüsseln. Dort können Sie es zurücksetzen; das alte Secret funktioniert sofort nicht mehr, aktualisieren Sie Ihren Empfänger also direkt nach dem Zurücksetzen.

Signatur prüfenCopy Anchor Link

Lehnen Sie die Anfrage mit 401 ab, wenn die Prüfung fehlschlägt, und verarbeiten Sie sie nicht. Erneutes Senden kann eine falsche Signatur nicht reparieren.

import crypto from 'node:crypto';

export function verify(rawBody, header, secret) {
  if (typeof header !== 'string') return false;
  const expected = Buffer.from('sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex'));
  const received = Buffer.from(header);
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

import hashlib, hmac
from typing import Optional

def verify(raw_body: bytes, header: Optional[str], secret: str) -> bool:
    if not header:
        return False
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(header.encode(), expected.encode())

Prüfen Sie gegen die unveränderten Bytes, bevor Sie das JSON parsen – erneutes Serialisieren ändert die Signatur. In Express lesen Sie den Body zum Beispiel mit express.raw({ type: 'application/json' }).