Überprüfen und verarbeiten Sie eingehende Webhooks

Wählen Sie die richtige Verifizierungsmethode

Die aktuelle Implementierung verfügt über zwei Bereitstellungsformate. Zu den signierten Dashboard-Ereignissen gehören Socialjuice-Signature und Socialjuice-Timestamp. Bei Bewertungsformularanfragen wird stattdessen X-Webhook-Secret verwendet. Bewahren Sie das Signaturgeheimnis Ihres Spaces nur auf dem empfangenden Server auf.

Wenn ein Signaturheader vorhanden ist, ist eine gültige HMAC-Überprüfung erforderlich. Akzeptieren Sie eine ungültige signierte Anfrage nicht als Legacy-Anfrage. Wenn Sie das Sammlungsformat unterstützen, benötigen Sie den genauen Shared-Secret-Header. Fehlende Authentifizierung ablehnen.

Überprüfen Sie eine signierte Anfrage

Lesen Sie den rohen Anforderungstext, bevor die JSON-Middleware ihn ändert. Die Signatur ist HMAC SHA-256 oder <timestamp>.<raw_request_body> mit dem Signaturgeheimnis. Socialjuice-Signature enthält t=<timestamp>,v1=<hex hmac>. Sein Zeitstempel muss mit Socialjuice-Timestamp übereinstimmen.

Verwenden Sie einen Digest-Vergleich mit konstanter Zeit. Lehnen Sie fehlerhafte Header und Zeitstempel ab, die mehr als fünf Minuten in der Vergangenheit oder Zukunft liegen. Halten Sie die Uhr Ihres Servers synchronisiert. Analysieren Sie nach der Überprüfung JSON und unterscheiden Sie webhook.test von testimonial.created.

Node.js HMAC-Beispiel

In diesem Beispiel wird nur das signierte Format überprüft. Geben Sie den Rohkörper als Buffer an, bevor JSON analysiert wird. Es werden keine X-Webhook-Secret-Erfassungsanforderungen authentifiziert.

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

export function verifySocialjuice(rawBody, headers, secret) {
  if (!secret || !Buffer.isBuffer(rawBody)) return false;
  const timestamp = headers.get('socialjuice-timestamp') || '';
  const signature = headers.get('socialjuice-signature') || '';
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(signature);
  if (!match || match[1] !== timestamp) return false;
  const seconds = Number(timestamp);
  if (!Number.isSafeInteger(seconds) ||
      Math.abs(Date.now() / 1000 - seconds) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(timestamp + '.')
    .update(rawBody)
    .digest();
  const received = Buffer.from(match[2], 'hex');
  return expected.length === received.length &&
    timingSafeEqual(expected, received);
}

Überprüfen Sie eine Abholanfrage

Lesen Sie X-Webhook-Secret und vergleichen Sie es mit dem konfigurierten Signaturgeheimnis auf Ihrem Server. Lehnen Sie einen leeren Header oder eine Nichtübereinstimmung ab. Behalten Sie den Endpunkt auf HTTPS und protokollieren Sie diesen Header niemals: Sein Wert ist das Geheimnis selbst.

Dieses Format enthält keinen signierten Zeitstempel oder eine garantierte Zustellungs-ID. Das obige HMAC-Beispiel kann nicht für den Wiedergabeschutz verwendet werden. Untersuchen Sie den tatsächlichen Körper, suchen Sie nach dem Testimonial uuid, sofern verfügbar, und deduplizieren Sie es an der vorgesehenen Stelle. Nutzlasten können flach sein oder ein verschachteltes Testimonial-Objekt enthalten.

Akzeptieren Sie schnell und vermeiden Sie Doppelarbeit

Verarbeiten Sie nur authentifizierte Anfragen. Deduplizieren Sie bei signierten Ereignissen mit Socialjuice-Delivery oder der Umschlag-ID. Verwenden Sie für Abholanfragen eine stabile Testimonial-ID, sofern verfügbar, und behalten Sie den Arbeitsbereichskontext bei. Speichern Sie Deduplizierungsdatensätze dauerhaft, wenn mehrere Serverinstanzen Ereignisse empfangen.

Geben Sie umgehend eine 2xx-Antwort zurück, nachdem Sie eine Anfrage sicher angenommen haben, und stellen Sie langsamere Arbeiten in die Warteschlange. Betrachten Sie webhook.test als einen Verbindungstest, nicht als echten Erfahrungsbericht. Ein bestandener Test beweist nicht, dass die Zuordnung Ihrer Sammlungsnutzlast korrekt ist.