Zum Hauptinhalt springen
Mit ausgehenden Webhooks können Ihre Systeme nahezu in Echtzeit auf Ereignisse in Flowella reagieren, ohne die API abzufragen. Sie konfigurieren eine URL und eine Liste von Ereignistypen, und Flowella POSTet eine signierte JSON-Nutzlast an diese URL, sobald eines dieser Ereignisse eintritt.

​
Konfigurieren eines Webhooks

Sie benötigen die Rolle Owner oder Admin.
1

Öffnen Sie Einstellungen → Webhooks

Gehen Sie in der Flowella-App zu Einstellungen → Webhooks.
2

Einen Webhook hinzufügen

Klicken Sie auf Webhook hinzufügen, fügen Sie die öffentliche HTTPS-URL Ihres Endpunkts ein, und wählen Sie die Ereignistypen aus, die Sie empfangen möchten.
3

Speichern Sie das Unterschriftsgeheimnis

Flowella generiert ein eindeutiges Signiergeheimnis für den Webhook. Kopieren Sie es - Sie werden es verwenden, um eingehende Anfragen zu verifizieren.
4

Einen Test senden

Klicken Sie auf Test senden, um eine webhook.test-Nutzlast sofort zu versenden. Vergewissern Sie sich, dass Ihr Endpunkt sie erhalten und mit einer 2xx geantwortet hat.

​
Ereignistypen

Sie können jedes dieser Produktereignisse abonnieren:
EreignisWenn es ausgelöst wird
message.receivedEine eingehende WhatsApp-Nachricht ist von einem Kontakt eingegangen
message.sentFlowella hat Ihre ausgehende Nachricht angenommen und an Meta übermittelt
message.deliveredMeta hat bestätigt, dass die Nachricht an das Gerät des Empfängers zugestellt wurde
message.readDer Empfänger hat die Nachricht geöffnet
message.failedMeta hat einen Fehler für die Nachricht zurückgegeben
conversation.openedEine Konversation ist in den offenen Zustand übergegangen
conversation.closedEine Konversation wurde geschlossen
optout.createdEin Kontakt hat sich für einen bestimmten Kanal abgemeldet
template.status_updatedMeta hat den Status einer Vorlage geändert (genehmigt, abgelehnt, pausiert, deaktiviert)
webhook.test wird nur gesendet, wenn Sie auf Test senden klicken - Sie abonnieren ihn nicht explizit.

​
Anfrageformat

Flowella POSTet einen JSON-Body an Ihre URL mit diesen Headern: 
POST https://your-endpoint.example.com/flowella
Content-Type: application/json
User-Agent: Flowella-Webhooks/1
X-Flowella-Signature: <hex digest>
Die Nutzdaten sind auf 256 KB begrenzt. Größere Objekte werden zusammengefasst - verwenden Sie die API, um den vollständigen Datensatz nach ID abzurufen, wenn Sie ihn benötigen. Die Form des Körpers variiert je nach Ereignis, umfasst aber immer: 
{
  "event": "message.delivered",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "organizationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": { "...event-specific fields..." }
}

​
Überprüfung von Signaturen

Jede Anfrage enthält einen X-Flowella-Signature-Header. Der Wert ist der HMAC-SHA256 Hex Digest des rohen UTF-8-Anfragekörpers, verschlüsselt mit dem Signiergeheimnis Ihres Webhooks. Überprüfen Sie ihn vor der Verarbeitung: 
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signatureHeader, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)
Signieren Sie immer über die raw body bytes, bevor JSON geparst wird oder Middleware die Nutzdaten neu formatiert. Wenn Ihr Framework JSON reserialisiert, wird die Signatur nicht übereinstimmen.

​
Antworten, Wiederholungsversuche und Zeitüberschreitungen

  • Timeout: Flowella wartet bis zu 10 Sekunden auf eine Antwort Ihres Endpunkts.
  • Erfolg: jede Antwort von 2xx wird als erfolgreiche Zustellung behandelt.
  • Wiederholungen: Fehlgeschlagene Zustellungen werden bis zu 3 Mal mit Backoff wiederholt.
  • Automatische Deaktivierung: Wenn ein Webhook 10 aufeinanderfolgende Fehlversuche aufweist, wird er von Flowella deaktiviert. Sie müssen ihn unter Einstellungen → Webhooks wieder aktivieren, nachdem Sie Ihren Endpunkt repariert haben.
Ihr Endpunkt sollte so schnell wie möglich zurückkehren. Verschieben Sie jede umfangreiche Verarbeitung in eine Hintergrundwarteschlange auf Ihrer Seite.

​
Idempotenz

Webhooks können erneut versucht werden, so dass dasselbe logische Ereignis mehr als einmal eintreffen kann. Zur sicheren Verarbeitung:
  • Verwenden Sie die data.id des Ereignisses (oder einen abgeleiteten Schlüssel wie event + data.messageId) als Idempotenzschlüssel.
  • Bewahren Sie einen kurzlebigen Cache der verarbeiteten Schlüssel auf (ein paar Stunden reichen für Wiederholungen aus).
  • Behandeln Sie Duplikate als No-ops.

​
Auflisten und Verwalten von Lieferungen

Einstellungen → Webhooks zeigt die letzten Zustellungsversuche pro Webhook an, einschließlich:
  • Zeitstempel
  • Ereignistyp
  • Status der Antwort
  • Ein verkürzter Antwortkörper (bis zu ~1 KB) zur Fehlersuche
Wenn ein Webhook aufgrund von wiederholten Fehlern deaktiviert wurde, können Sie ihn auf derselben Seite wieder aktivieren.

​
Lokale Entwicklung

Die einfachste Möglichkeit, lokal gegen Webhooks zu entwickeln, besteht darin, einen öffentlichen Tunnel (z.B. ngrok oder Cloudflare Tunnel) an Ihren Entwicklungsserver weiterzuleiten und die Webhook-URL auf den Tunnelhost zu verweisen. Verwenden Sie Send test, um Payloads bei Bedarf abzufeuern, ohne auf echte WhatsApp-Aktivität zu warten.
Müssen Sie auf Ereignisse reagieren, die nicht in der Liste aufgeführt sind? Teilen Sie uns dies unter support mit - wir fügen Ereignisse hinzu, wenn Kunden danach fragen.

​
Verwandt

Einstellungen → Webhooks

Konfigurieren Sie Endpunkte, Signiergeheimnisse und Wiederholungsversuche in der App.

API-Einführung

Autorisierung, Fehler, Paginierung und Ratenbegrenzung für die REST-API.

API-Schlüssel

Erstellen und drehen Sie die Inhaber-Tokens, die Ihr Endpunkt möglicherweise benötigt.

Ereignisse zur Benachrichtigung

Die gleichen Ereignisse in den In-App-Feed und in die E-Mail übertragen.