Webhook-Signaturen überprüfen

Jede Anfrage an einen benutzerdefinierten Endpoint wird mit dem Secret deines Endpoints signiert. Prüfe die Signatur, bevor du dem Body vertraust.

Wie signiert wird

• Die Signatur ist ein HMAC-SHA256 des rohen Request-Bodys, berechnet mit deinem Signing Secret.
• Sie wird als X-Studio-Signature: sha256=<hex digest> gesendet.
• Secrets beginnen mit whsec_. Du findest deins unter Signing secret auf der Seite des Endpoints.

Node.js

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

export function verify(rawBody: string, header: string, secret: string) {
  const expected = `sha256=${createHmac("sha256", secret).update(rawBody).digest("hex")}`
  const a = Buffer.from(header)
  const b = Buffer.from(expected)
  return a.length === b.length && timingSafeEqual(a, b)
}

Python

import hashlib, hmac

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

Häufige Fehler

• Hash die exakten Bytes, die du erhalten hast. Wenn du das JSON parst und erneut serialisierst, ändern sich die Bytes, und die Signatur stimmt nicht mehr.
• Verwende einen Vergleich in konstanter Zeit, wie in den Beispielen oben, statt ==.
• Nach Rotate secret musst du deinen Server sofort aktualisieren. Das alte Secret funktioniert dann nicht mehr.

Chat-App-Ziele wie Slack erhalten stattdessen eine formatierte Nachricht und werden nicht signiert.