Signaturvalidierung

Bevor Ihre Anwendung einer Webhook-Anfrage vertraut, sollte sie verifizieren, dass die Anfrage tatsächlich von Blazelock stammt und dass das Payload auf dem Weg zu Ihrem Endpunkt nicht verändert wurde. Das hilft dabei, die Authentizität zu bestätigen, manipulierte Payloads zu erkennen und das Risiko von Replay-Angriffen zu reduzieren.

Header

Jede Webhook-Anfrage enthält diese Header:

Ihr Webhook-Secret finden Sie im Blazelock Dashboard in den Einstellungen der API-Anbindung.

Validierungsschritte

1. Timestamp prüfen: Verifizieren Sie, dass der Zeitstempel aus dem X-Blazelock-Webhook-Timestamp-Header innerhalb eines akzeptablen Zeitfensters liegt, beispielsweise 5 Minuten, um Replay-Angriffe zu verhindern.
2. Signiertes Payload erstellen: Das signierte Payload ist die exakte Verkettung aus drei Teilen: dem Wert des X-Blazelock-Webhook-Timestamp-Headers, einem Punkt (.) und dem rohen Request-Body genau in der Form, in der er empfangen wurde.

Beispiel:

1737830031.{"event":"file_scan.completed","integration_id":"...","occurred_at":"...","data":{...}}

3. Erwartete Signatur berechnen: Erzeugen Sie für das Payload aus Schritt 2 eine HMAC-SHA256-Signatur mit Ihrem Webhook-Secret aus dem Blazelock Dashboard.
4. Signaturen vergleichen: Vergleichen Sie die von Ihnen berechnete Signatur mit dem Wert aus dem X-Blazelock-Webhook-Signature-Header mithilfe eines time-safe Vergleichs.
5. Ereignis verarbeiten: Verarbeiten Sie das Webhook-Ereignis erst, nachdem die Signaturprüfung erfolgreich war.

Code-Beispiele

Die folgenden Beispiele konzentrieren sich ausschließlich auf die Signaturverifizierung. Sie setzen voraus, dass Ihnen bereits der rohe Request-Body, die beiden Header und Ihr Webhook-Secret vorliegen.

import crypto from 'node:crypto'

export function validateBlazelockWebhook(rawBody, timestampHeader, signatureHeader, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(`${timestampHeader}.${rawBody}`)
    .digest('hex')

  const providedSignature = Buffer.from(signatureHeader)
  const expectedSignatureBuffer = Buffer.from(expectedSignature)

  if (providedSignature.length !== expectedSignatureBuffer.length) {
    return false
  }

  return crypto.timingSafeEqual(providedSignature, expectedSignatureBuffer)
}