Webhooks

Worum geht es hier?

Webhooks bei Alpheris gibt es in beide Richtungen. Ausgehend ist der Teil, den du selbst einrichtest: Du hinterlegst im Dashboard eine URL, und wir schicken die dort abonnierten Ereignisse als signierten POST dorthin — das steht gleich unten. Eingehend läuft umgekehrt und ohne dein Zutun: Externe Plattformen, die du mit deinem Shop verbunden hast, melden Ereignisse an Alpheris zurück — zum Beispiel eine neue Instagram-DM, eine geänderte Stripe-Subscription oder eine deinstallierte Shopify-App. Alpheris richtet diese Endpunkte automatisch beim Verbinden der jeweiligen Integration ein. Du musst in der Regel nichts manuell registrieren.

Ausgehende Webhooks

Seit dem Dashboard-Bereich Webhooks kannst du eigene Endpunkte hinterlegen: Alpheris schickt die dort abonnierten Ereignisse als POST an deine URL — signiert, damit du prüfen kannst, dass die Anfrage wirklich von uns stammt. Zu finden im Dashboard in der linken Leiste unter Webhooks, direkt unter API Keys. Verfügbar ab Business, verwalten dürfen es Owner und Admins.

Ereignisse

Aufbau des Payloads

{
  "id": "evt_9f2c1a4b7e8d0c3a5b6f2e11",
  "type": "ticket.created",
  "created_at": 1785062400,
  "data": { }
}

Signatur prüfen

Jede Zustellung trägt zwei Header. Signiert wird der rohe Body, dem der Zeitstempel mit einem Punkt vorangestellt wird — also <timestamp>.<body>, per HMAC-SHA256 mit deinem Signing Secret, hexadezimal:

import hmac, hashlib

def signatur_ok(roh_body: bytes, headers, secret: str) -> bool:
    ts  = headers["X-Alpheris-Timestamp"]
    sig = headers["X-Alpheris-Signature"]
    erwartet = "sha256=" + hmac.new(
        secret.encode(), ts.encode() + b"." + roh_body, hashlib.sha256
    ).hexdigest()
    # zeitkonstant vergleichen, nie mit ==
    return hmac.compare_digest(sig, erwartet)

Gut zu wissen

Was Alpheris sonst noch nach außen ruft

Lead-Formulare können ihre Daten zusätzlich direkt an deine API pushen — Einrichtung und Payload stehen unter Lead-Erfassung → Formular-Webhook. Alle übrigen ausgehenden Aufrufe richten sich ausschließlich an die nötigen Drittdienste (E-Mail über Microsoft Graph, Antworten an Meta, Abrechnung über Stripe) und sind kein konfigurierbarer Webhook.

Eingehende Webhooks im Überblick

Alle eingehenden Webhook-Routen prüfen den rohen Request-Body gegen eine Signatur des Absenders. Schlägt die Prüfung fehl, wird der Request abgewiesen — es gibt keinen ungeprüften Verarbeitungspfad.

Shopify-Webhooks

Beim Verbinden eines Shopify-Stores per OAuth registriert Alpheris die App-Webhooks automatisch und empfängt sie unter POST /shopify/webhooks (Alias: /api/integrations/shopify/webhooks). Verarbeitet werden u. a. App-Deinstallation, Shop-Update und Produkt-Delta-Sync, damit dein Katalog in der Wissensbasis aktuell bleibt.

Die Echtheit wird über den Header X-Shopify-Hmac-Sha256 geprüft: Alpheris berechnet einen HMAC-SHA256 über den rohen Body mit dem App-Secret und vergleicht ihn zeitkonstant (Base64) gegen den Header.

# So prüft Alpheris die Shopify-Signatur (vereinfacht)
import hmac, hashlib, base64

digest = base64.b64encode(
    hmac.new(app_secret.encode("utf-8"), raw_body, hashlib.sha256).digest()
).decode("utf-8")

valid = hmac.compare_digest(digest, request.headers["X-Shopify-Hmac-Sha256"])

Stripe-Webhooks

Stripe meldet Abrechnungs-Ereignisse an POST /stripe/webhook. Daraus hält Alpheris deinen Plan und Abo-Status synchron — etwa wenn ein Abo erstellt, aktualisiert oder gekündigt wird oder eine Rechnung bezahlt bzw. fehlschlägt.

Die Verifizierung läuft über die offizielle Stripe-Bibliothek mit dem Header Stripe-Signature und dem Webhook-Secret (construct_event). Ungültige Signaturen werden mit 400 abgewiesen.

Idempotenz

Stripe stellt Events bei Netzwerk- oder Timeout-Fehlern erneut zu. Damit ein Event nie doppelt wirkt (keine Doppel-Provisionierung, keine doppelten Mails), führt Alpheris einen Idempotenz-Store: Jede Event-ID wird vor der Verarbeitung atomar „beansprucht". Bereits gesehene Events werden mit ok (duplicate) übersprungen.

Meta-Webhooks (Instagram & WhatsApp)

Instagram und WhatsApp werden per Meta-OAuth verbunden. Eingehende Nachrichten und Ereignisse erreichen Alpheris über die Callback-Endpunkte und landen in deiner Inbox. Beide nutzen das Meta-Standardverfahren: Signaturprüfung über X-Hub-Signature-256 (HMAC-SHA256 über den rohen Body mit dem App-Secret).

Verify-Handshake (WhatsApp)

Beim Einrichten des WhatsApp-Webhooks führt Meta einen einmaligen Verify-Handshake aus: ein GET-Request mit hub.challenge und hub.verify_token. Alpheris prüft das Verify-Token und spiegelt die Challenge zurück, sobald es passt. Danach werden nur noch signierte POST-Events angenommen.

# Eingehender Meta-Event (vereinfacht)
POST /integrations/instagram/callback
X-Hub-Signature-256: sha256=<hex-digest>
Content-Type: application/json

# Alpheris verifiziert sha256(raw_body, app_secret) gegen den Header,
# bevor die Nachricht in die Inbox übernommen wird.

Eigene Events abholen (Polling)

Solange die Ereignisse oben noch nicht ausgelöst werden — und generell für den vollständigen Bestand statt einzelner Ereignisse — nutze die API-Referenz. Authentifiziere dich per API-Key und frage die relevanten Endpunkte regelmäßig ab.

# Neue Inbox-Threads abholen (Polling statt Outbound-Webhook)
curl -sS https://console.alpheris.com/api/inbox/threads \
  -H "Authorization: Bearer <SHOP_API_KEY>"

Häufige Fragen

Muss ich eine Webhook-URL irgendwo eintragen?

Nein. Die eingehenden Webhooks werden beim Verbinden der jeweiligen Integration (Shopify, Stripe-Checkout, Meta-OAuth) automatisch eingerichtet.

Warum schlägt eine Signaturprüfung fehl?

Fast immer, weil ein Proxy oder Middleware den Body verändert hat oder ein falsches/abgelaufenes Secret im Spiel ist. Da gegen den rohen Body geprüft wird, dürfen zwischen Empfang und Prüfung keine Umformatierungen passieren. Prüfe in dem Fall die Integration im Dashboard und verbinde sie ggf. neu.

Kann Alpheris mein System bei jeder neuen Nachricht benachrichtigen?

Aktuell nicht per Push. Nutze stattdessen Polling über die API (siehe oben).