Raw Webhook adapter

The Raw Webhook adapter sends allowed KALYIX extension events as raw JSON deliveries to your own server or receiver using HTTPS POST. Use it when you want to connect KALYIX to your own backend, automation service, or external platform.

The adapter intentionally does not build Discord, Slack, or Telegram messages. If you want to use those services, place a small mapper between KALYIX and the target system:

KALYIX Raw Webhook -> your receiver/mapper -> Discord, Slack, Telegram, ...

Requirements

• A publicly reachable https:// URL.
• A Raw Webhook adapter in the Extensions Dashboard.
• The signing secret shown once when you create or rotate the Webhook adapter.
• Enabled events and fields, for example Tip paid, amount, currency, and username.

Setup

1. Open the Extensions Dashboard.
2. Enable the Raw Webhook adapter.
3. Enter your HTTPS endpoint URL.
4. Save the URL.
5. Copy the signing secret and store it securely on your server.
6. Enable the Tip paid event.
7. Select the fields your endpoint should receive.
8. Save the selection.
9. Use Send test to verify the connection.

Request

KALYIX sends JSON to your endpoint:

POST /your-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=...

The body uses this 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": "Thank you!"
    },
    "createdAt": "2026-07-07T12:00:00.000Z"
  },
  "delivery": {
    "attempts": 1,
    "createdAt": "2026-07-07T12:00:01.000Z",
    "claimedAt": "2026-07-07T12:00:02.000Z"
  }
}

Verify the signature

Verify every request before processing the body. KALYIX signs the unchanged raw body with your signing secret:

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

The header contains the signature as:

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

Recommended checks:

• Use the raw body, not re-serialized JSON.
• Check the timestamp, for example allow at most 5 minutes drift.
• Compare signatures with a timing-safe comparison.
• Return 401 for invalid signatures.

Responses and retry

Only respond with 2xx after your endpoint really accepted the event. If your system is temporarily unavailable, respond with 5xx or let the request fail so KALYIX can retry.

Fields

KALYIX only sends fields you enable in the Extensions Dashboard.

• Disabled fields are omitted completely.
• Enabled but empty fields are sent as null.
• Tests use the same tip.paid event but are not stored as real payments in Tip payment history.

Examples

The Downloads page includes example receivers for:

• Node/Express
• PHP

Both examples verify the KALYIX signature before processing the event.

Direct Discord or Slack URLs?

Do not enter a Discord or Slack webhook URL directly as a Raw Webhook target. Those services expect their own message format, while KALYIX sends the unchanged KALYIX delivery here.

For Discord without your own server, use the Discord Webhook adapter. For other services, use your own receiver or a future dedicated KALYIX adapter.