Webhooks

Eingehende Webhook-Endpunkte für Meta-Kanäle: Facebook Messenger, Instagram DM und WhatsApp.

Kurzüberblick#

Webhooks werden unter helpstack.eu empfangen; die Callback-URL registrieren Sie im Meta-App-Dashboard. Der Verify-Token und das App-Secret werden durch HelpStack konfiguriert (siehe die unten referenzierten Umgebungsvariablen).

Funktionsweise des Handshakes (alle Anbieter)#

Meta verifiziert einen Webhook, indem es ein GET mit drei Query-Parametern sendet. HelpStack gibt die Challenge nur zurück, wenn der Verify-Token übereinstimmt.

GET /api/webhooks/facebook
  ?hub.mode=subscribe
  &hub.verify_token=TOKEN
  &hub.challenge=CHALLENGE

• Wenn TOKEN dem konfigurierten Verify-Token entspricht → mit 200 und dem rohen CHALLENGE-Wert antworten.
• Andernfalls → mit 403 antworten.

Funktionsweise der Signaturverifizierung (alle Anbieter)#

Jeder POST trägt einen x-hub-signature-256-Header. Die Signatur wird über den rohen Request-Body mit HMAC-SHA256 berechnet, gehasht mit FACEBOOK_APP_SECRET, und mit sha256= prefixiert.

x-hub-signature-256: sha256=<hex HMAC-SHA256(rawBody, FACEBOOK_APP_SECRET)>

Node-Beispiel (Berechnung/Verifizierung):

import crypto from 'node:crypto';

function verifySignature(rawBody, headerValue, appSecret) {
  const expected =
    'sha256=' +
    crypto.createHmac('sha256', appSecret).update(rawBody).digest('hex');
  return headerValue === expected;
}

Achtung — verwenden Sie den rohen Body. Die Signatur wird über die exakten Bytes berechnet, die Meta gesendet hat. HelpStack liest den Body als rohen Text, bevor JSON geparst wird. Wenn Sie eine eigene Verifizierung erstellen, dürfen Sie das geparste JSON-Objekt nicht erneut serialisieren (Schlüsselreihenfolge/Leerzeichen weichen ab und die Signatur stimmt nicht überein). Erfassen Sie den rohen Body-String und berechnen Sie dessen HMAC.

Facebook / Messenger#

Struktur des eingehenden Payloads. Der Body enthält ein entry[]-Array. Jeder Eintrag hat entweder:

• entry[].messaging[] — älteres Messenger-Format, oder
• entry[].changes[] — neueres Format.

Kanalabgleich & Verarbeitung. Der Handler gleicht einen Kanal über facebookPageId / credentials.pageId ab und:

1. Erstellt oder aktualisiert ein Gespräch, das durch die PSID des Absenders identifiziert wird.
2. Speichert die eingehende Nachricht.
3. Ruft das Profil des Absenders ab und lädt Anhänge in den Speicher herunter.
4. Sendet ein Echtzeit-Ereignis an das Dashboard.

Instagram#

Gleicht OAuth-verwaltete Kanäle über die Instagram-Konto-ID ab. Handshake und Signaturverifizierung funktionieren wie bei Facebook.

WhatsApp#

Struktur des eingehenden Payloads. Der Body enthält entry[].changes[].value mit messages[] und contacts[]. Der Handler gleicht einen Kanal über credentials.phoneNumberId ab und identifiziert das Gespräch über die Telefonnummer des Absenders.

Umgebungsvariablen#

Registrierung im Meta-App-Dashboard#

Für Messenger (dasselbe Muster gilt für Instagram und WhatsApp mit ihren jeweiligen Endpunkten):

1. Öffnen Sie im Meta-App-Dashboard das Produkt (Messenger / Instagram / WhatsApp) → Webhooks.
2. Callback-URL: https://helpstack.eu/api/webhooks/facebook (Instagram: .../api/webhooks/instagram, WhatsApp: .../api/webhooks/whatsapp.)
3. Verify-Token: der Wert, den Sie in FACEBOOK_VERIFY_TOKEN gesetzt haben (oder der anbieterspezifische Token).
4. Klicken Sie auf Verify and Save — Meta sendet den GET-Handshake; er ist erfolgreich, wenn der Token übereinstimmt.
5. Felder abonnieren: abonnieren Sie die Felder messages / messaging, damit Nachrichtenereignisse zugestellt werden.
6. Stellen Sie sicher, dass das App Secret Ihrer App mit FACEBOOK_APP_SECRET übereinstimmt, damit die Signaturverifizierung bei POST erfolgreich ist.

Senden Sie nach dem Speichern eine Testnachricht an die Seite/das Konto — sie sollte als neues Gespräch im Dashboard erscheinen.

Verwandte Themen#

• API-Referenz
• E-Mail-Kanal
• Kanäle-Leitfaden
• Glossar