Raw Webhook Adapter

Mit dem Raw Webhook Adapter sendet KALYIX erlaubte Extension-Events als rohe JSON Delivery per HTTPS POST an deinen eigenen Server oder Receiver. Das ist sinnvoll, wenn du KALYIX mit einem eigenen Backend, Automatisierungsdienst oder einer externen Plattform verbinden möchtest.

Der Adapter baut bewusst keine Discord-, Slack- oder Telegram-Nachricht. Wenn du solche Dienste nutzen möchtest, brauchst du einen kleinen Mapper zwischen KALYIX und dem Zielsystem:

KALYIX Raw Webhook -> dein Receiver/Mapper -> Discord, Slack, Telegram, ...

Was du brauchst

• Eine öffentlich erreichbare https:// URL.
• Einen Raw Webhook Adapter im Extensions Dashboard.
• Das Signing Secret, das beim Erstellen oder Rotieren des Webhook Adapters einmalig angezeigt wird.
• Aktivierte Events und Datenfelder, zum Beispiel Tip bezahlt, amount, currency und username.

Einrichtung

1. Öffne das Extensions Dashboard.
2. Aktiviere den Adapter Raw Webhook.
3. Trage deine HTTPS Endpoint URL ein.
4. Speichere die URL.
5. Kopiere das Signing Secret und speichere es sicher in deinem Server.
6. Aktiviere das Event Tip bezahlt.
7. Wähle die Datenfelder aus, die dein Endpoint erhalten soll.
8. Speichere die Auswahl.
9. Nutze Test senden, um die Verbindung zu prüfen.

Request

KALYIX sendet JSON an deinen Endpoint:

POST /dein-endpoint HTTP/1.1
content-type: application/json
user-agent: KALYIX-Webhooks/1.0
x-kalyix-event: tip.paid
x-kalyix-delivery-id: ...
x-kalyix-timestamp: 1783430000
x-kalyix-signature: v1=...

Der Body hat dieses Format:

{
  "type": "delivery",
  "deliveryId": "delivery-id",
  "event": {
    "id": "event-id",
    "sourceDomain": "tipp",
    "eventType": "tip.paid",
    "payload": {
      "amount": 25,
      "amountCents": 2500,
      "currency": "EUR",
      "username": "supporter",
      "message": "Danke!"
    },
    "createdAt": "2026-07-07T12:00:00.000Z"
  },
  "delivery": {
    "attempts": 1,
    "createdAt": "2026-07-07T12:00:01.000Z",
    "claimedAt": "2026-07-07T12:00:02.000Z"
  }
}

Signatur prüfen

Prüfe jeden Request, bevor du den Body verarbeitest. KALYIX signiert den unveränderten Raw Body mit deinem Signing Secret:

HMAC-SHA256(secret, "{x-kalyix-timestamp}.{rawBody}")

Der Header enthält die Signatur als:

x-kalyix-signature: v1=<hex-signature>

Empfohlen:

• Raw Body verwenden, nicht neu serialisiertes JSON.
• Timestamp prüfen, zum Beispiel maximal 5 Minuten Abweichung.
• Signatur mit timing-safe Vergleich prüfen.
• Bei ungültiger Signatur 401 zurückgeben.

Antworten und Retry

Antworte erst mit 2xx, wenn du das Event wirklich angenommen hast. Wenn dein System gerade nicht bereit ist, antworte mit 5xx oder lasse den Request fehlschlagen, damit KALYIX erneut zustellen kann.

Datenfelder

KALYIX sendet nur Felder, die du im Extensions Dashboard aktivierst.

• Nicht aktivierte Felder fehlen komplett.
• Aktivierte, aber leere Felder werden als null gesendet.
• Tests verwenden dasselbe Event tip.paid, werden aber nicht als echte Zahlung in der Tip-Zahlungshistory gespeichert.

Beispiele

Auf der Downloads-Seite findest du Beispiel-Receiver für:

• Node/Express
• PHP

Beide Beispiele prüfen die KALYIX Signatur, bevor sie das Event verarbeiten.

Direkt an Discord oder Slack?

Trage keine Discord- oder Slack-Webhook-URL direkt als Raw Webhook Ziel ein. Diese Dienste erwarten ihr eigenes Nachrichtenformat, KALYIX sendet hier aber die unveränderte KALYIX Delivery.

Für Discord ohne eigenen Server nutze den Discord Webhook Adapter. Für andere Dienste brauchst du einen eigenen Receiver oder später einen passenden KALYIX Adapter.