Webhook-Benachrichtigung hinzufügen

Dieser Leitfaden erklärt, wie Sie eine Webhook-Benachrichtigung einrichten und eingehende MERGEPORT Webhooks sicher verifizieren.

Webhook-Benachrichtigungen ermöglichen es MERGEPORT, Ereignisse in Echtzeit per HTTP an externe Systeme zu senden. Sie werden häufig verwendet, um eingehende Bestellungen an Drittsysteme weiterzuleiten, können aber auch für andere Integrationen genutzt werden – etwa für Kassensysteme, Monitoring-Tools oder individuelle Workflows.

Voraussetzungen

Webhook-Benachrichtigungen können nicht parallel zu einer aktiven POS-Integration verwendet werden. Ist für einen Standort bereits eine Kassensystem-Anbindung aktiv, werden über den Webhook keine Bestellereignisse gesendet.

Webhook einrichten

Die gesamte Konfiguration erfolgt im MERGEPORT Controller.

1. Öffnen Sie die Integrationseinstellungen Navigieren Sie zu dem Restaurant/Standort, den Sie konfigurieren möchten.
2. Öffnen Sie „Zusatzservices anbinden“ Hinterlegen Sie die öffentliche HTTPS-Adresse Ihres Webhook-Endpunkts unter Webhook URL.
3. Hinterlegen Sie den Secret Key Das Secret muss auch im empfangenden System sicher gespeichert werden. Es darf nicht öffentlich weitergegeben oder protokolliert werden.
4. Wählen Sie den Webhook Signing Mode Verwenden Sie für neue Integrationen Standard Webhooks. Der Modus Legacy bleibt für bestehende Integrationen verfügbar.
5. Konfigurieren Sie die Weiterleitung Optional können Sie nur angenommene Bestellungen oder alle Statusänderungen weiterleiten.
6. Speichern und testen Sie die Konfiguration Senden Sie eine Testbestellung über eine Bestellplattform oder eine Staging-Umgebung, um die Verbindung zu prüfen.

Legacy und Standard Webhooks

Im Modus Legacy oder wenn kein Signing Mode gesetzt ist, sendet MERGEPORT den Secret Key weiterhin im HTTP-Header Authorization. Die Standard-Webhooks-Header werden in diesem Modus nicht gesendet.

Im Modus Standard Webhooks ist der Secret Key Pflicht. MERGEPORT verwendet ihn ausschließlich zur Berechnung der Signatur und sendet ihn nicht im Authorization-Header.

Jeder Request enthält dann:

• webhook-id: eindeutige ID der Zustellung; sie bleibt bei Wiederholungsversuchen gleich.
• webhook-timestamp: Unix-Zeitstempel in Sekunden.
• webhook-signature: HMAC-SHA256-Signatur im Format v1,<base64>.

Die Signatur wird über folgenden unveränderten String gebildet:

{webhook-id}.{webhook-timestamp}.{raw-request-body}

Verifizieren Sie die Signatur gegen die unveränderten Bytes des HTTP-Request-Bodys. Parsen oder serialisieren Sie JSON nicht erneut, bevor Sie die Signatur prüfen. Das folgende Node.js-Beispiel erwartet deshalb rawBody als Buffer und verwirft unvollständige, abgelaufene oder ungültig signierte Requests:

const crypto = require("crypto");

function verifyWebhook(headers, rawBody, secret, toleranceSeconds = 300) {
  const id = readSingleHeader(headers, "webhook-id");
  const timestamp = readSingleHeader(headers, "webhook-timestamp");
  const signature = readSingleHeader(headers, "webhook-signature");

  if (!id || !timestamp || !signature || !Buffer.isBuffer(rawBody)) return false;

  const timestampSeconds = Number(timestamp);
  const nowSeconds = Math.floor(Date.now() / 1000);
  if (
    !/^\d+$/.test(timestamp) ||
    !Number.isSafeInteger(timestampSeconds) ||
    timestampSeconds <= 0 ||
    Math.abs(nowSeconds - timestampSeconds) > toleranceSeconds
  ) return false;

  const signedContent = Buffer.concat([
    Buffer.from(`${id}.${timestamp}.`, "utf8"),
    rawBody,
  ]);
  const expected = Buffer.from("v1," + crypto
    .createHmac("sha256", secret)
    .update(signedContent)
    .digest("base64"), "utf8");
  const received = Buffer.from(signature, "utf8");

  return received.length === expected.length &&
    crypto.timingSafeEqual(received, expected);
}

function readSingleHeader(headers, name) {
  const value = headers[name];
  return typeof value === "string" ? value : undefined;
}

Speichern Sie eine webhook-id erst nach erfolgreicher Signaturprüfung und dann atomar als verarbeitet. Verarbeiten Sie dieselbe ID nur einmal. So schützen Sie Ihre Integration vor verspäteten Wiederholungen und doppelter Verarbeitung.

Hilfe bei Problemen

Falls diese Schritte das Problem nicht lösen, wenden Sie sich bitte an den Support unter support@mergeport.com.