Webhooks

Lumio exposes a small set of inbound webhook endpoints under /v1/webhooks/* that receive platform event notifications (chat, subscriptions, follows, orders, payments) and fan them out into the same lo-events / lo-chat pipelines used by the rest of the stack. This page is the public contract for those endpoints.

Overview

Platform	Endpoint	Verification	Source crate
YouTube	POST /v1/webhooks/youtube (+ GET for verify)	PubSubHubbub challenge echo	lo-youtube-api
Kick	POST /v1/webhooks/kick	HMAC-SHA256 (X-Kick-Signature)	lo-kick-api
Trovo	POST /v1/webhooks/trovo	HMAC-SHA256 (X-Trovo-Signature)	lo-trovo-api
Shopify	POST /v1/webhooks/shopify	HMAC-SHA256 (X-Shopify-Hmac-SHA256)	lo-shopify
Stripe	POST /v1/webhooks/stripe	Stripe-Signature (t=…, v1=…)	stripe-rust

All endpoints are unauthenticated — they are protected by per-platform signature verification, not JWT or API key auth. Callers are expected to be the platform itself, not Lumio users.

Route wiring lives in apps/api/src/routes/webhooks.rs (platforms) and apps/api/src/routes/billing.rs (Stripe).

Twitch is not in this list. Twitch events do not arrive via HTTP webhook in Lumio — see Twitch (EventSub, WebSocket) below.

Twitch (EventSub, WebSocket, not webhook)

Twitch events do not use a webhook in Lumio. Instead, the API server runs a background worker (apps/api/src/workers/twitch_eventsub.rs) that opens a persistent EventSub WebSocket connection to wss://eventsub.wss.twitch.tv/ws per account, then calls the Helix POST /eventsub/subscriptions endpoint to register subscriptions with transport: { method: "websocket", session_id }.

Subscribed types are defined in subscription_types::ALL in crates/lo-twitch-api/src/types.rs and include: channel.follow, channel.cheer, channel.raid, channel.channel_points_custom_reward_redemption.add, stream.online, stream.offline, channel.chat.message, channel.chat.notification, channel.ban, channel.unban, channel.moderate, hype-train / poll / prediction / goal / ad-break events, and suspicious-user signals.

There is no HTTP endpoint to expose. Lifecycle is fully managed by the worker — subscriptions are recreated on every reconnect and cleaned up when the channel connection is removed.

YouTube (PubSubHubbub)

YouTube uses Google's PubSubHubbub (WebSub) hub at https://pubsubhubbub.appspot.com to push Atom XML feed updates.

Endpoints

• GET https://api.lumio.vision/v1/webhooks/youtube — subscription verification. The hub sends hub.mode, hub.topic, hub.challenge, hub.lease_seconds as query params; Lumio echoes hub.challenge back with a 200 text/plain response.
• POST https://api.lumio.vision/v1/webhooks/youtube — notifications. Body is Atom XML; the handler extracts <yt:channelId> and <yt:videoId> via lo_youtube_api::webhook::parse_atom_notification.

Lifecycle. Lumio subscribes by POSTing to the PubSubHubbub hub with hub.callback = https://api.lumio.vision/v1/webhooks/youtube and hub.topic = https://www.youtube.com/xml/feeds/videos.xml?channel_id=\{YT_CHANNEL_ID\}. Leases must be renewed (default: a few days) — the token-refresh / channel-sync workers re-subscribe automatically.

Events emitted. Every notification becomes a single youtube:subscribe event (see routes/webhooks.rs:124). The raw payload preserves channel_id, video_id, title, published, updated.

Security. No signature is used — PubSubHubbub relies on the hub.secret parameter when subscribing; Lumio currently does not set one. If you need strict verification, add an HMAC check on the X-Hub-Signature header in the handler.

Kick

Endpoint. POST https://api.lumio.vision/v1/webhooks/kick, Content-Type: application/json.

Signature. Optional. If kick_webhook_secret is set in apps/api/config/*.toml (LUMIO__KICK_WEBHOOK_SECRET), the handler requires X-Kick-Signature: [sha256=]<hex> and verifies it with constant-time HMAC-SHA256 via lo_kick_api::webhook::verify_signature. If no secret is configured, the endpoint accepts unsigned payloads (useful in local dev).

Events received (from lo_kick_api::types::event_types):

• channel.subscription.new → kick:subscribe
• channel.subscription.gift → kick:gift
• channel.followed → kick:follower
• livestream.started → kick:stream_online
• livestream.ended → kick:stream_offline
• chat.message.sent → routed to the chat pipeline (ChatBuffer + pubsub), not the events pipeline.
• moderation.banned → routed to the moderation-log pipeline with dedup + broadcast.

Account resolution is by payload.channel_id against channel_connections where platform = 'kick'.

Subscription. Kick webhook subscriptions are created via the connection flow in apps/api/src/routes/connections.rs using the bot OAuth token against Kick's public API; the callback URL is configured per-environment.

Trovo

Endpoint. POST https://api.lumio.vision/v1/webhooks/trovo.

Signature. Optional HMAC-SHA256 of the body, X-Trovo-Signature header, secret in trovo_webhook_secret (LUMIO__TROVO_WEBHOOK_SECRET). Implementation is identical in shape to Kick — see crates/lo-trovo-api/src/webhook.rs.

Events received (from lo_trovo_api::types::event_types):

• channel.subscribe → trovo:subscribe
• channel.spell → trovo:spell (Trovo's cheers/tips)

Account resolution is by payload.channel_id against channel_connections where platform = 'trovo'.

Shopify

Endpoint. POST https://api.lumio.vision/v1/webhooks/shopify.

Headers required:

• X-Shopify-Topic — e.g. orders/create, orders/paid, products/create.
• X-Shopify-Shop-Domain — the *.myshopify.com domain.
• X-Shopify-Hmac-SHA256 — base64-encoded HMAC-SHA256 of the raw body.

Signature. Per-shop. The secret is stored in integration_configs.config.webhook_secret (not a global env var) and looked up by shop_domain via db::connections::find_integration_by_shop_domain. Verified with lo_shopify::webhook::verify_hmac.

Events mapped (lo_shopify::types::event_topics → Lumio type):

• orders/create → shopify:order
• orders/paid → shopify:order_paid
• products/create → shopify:product

Any other topic returns 200 and is dropped silently. Parsing lives in lo_shopify::webhook::parse_order_webhook and parse_product_webhook.

Stripe

Endpoint. POST https://api.lumio.vision/v1/webhooks/stripe (wired in routes/billing.rs, not routes/webhooks.rs).

Signature. Stripe-Signature header (format t=<timestamp>,v1=<hex>), verified against config.stripe.webhook_secret (LUMIO__STRIPE__WEBHOOK_SECRET) by the in-file verify_stripe_signature helper.

Events handled:

• checkout.session.completed — finalises the account/plan binding (creates an account for new signups or upgrades an existing one via metadata.account_id / metadata.user_id).
• customer.subscription.updated — updates the plan on an account and refreshes current_period_end.
• customer.subscription.deleted — downgrades to the free plan.
• invoice.payment_failed — logged for now.

All other Stripe event types are acknowledged with 200 and ignored. Feature-flag caches are invalidated on every plan change.

Registering subscriptions

There is no public "register a webhook" Lumio endpoint. Subscriptions are created in one of three ways:

1. Automatic, at connection time. When a user connects a Kick / Trovo / YouTube channel via apps/api/src/routes/connections.rs, the connection worker (or the sync job in workers/) registers the corresponding platform subscription using the newly-stored OAuth token.
2. Automatic, at worker startup. The Twitch EventSub worker registers all subscription_types::ALL every time it (re)connects.
3. Admin-controlled for Shopify & Stripe. These are configured in the platform's own dashboard (Shopify admin → Notifications → Webhooks, Stripe dashboard → Developers → Webhooks). The callback URL is https://api.lumio.vision/v1/webhooks/{platform} and the signing secret is copied into integration_configs.config.webhook_secret (Shopify) or the Lumio TOML config (Stripe).

Configuration / env vars

Key	TOML path	Env var	Used by
Kick webhook secret	kick_webhook_secret	LUMIO__KICK_WEBHOOK_SECRET	Kick endpoint
Trovo webhook secret	trovo_webhook_secret	LUMIO__TROVO_WEBHOOK_SECRET	Trovo endpoint
Stripe webhook secret	stripe.webhook_secret	LUMIO__STRIPE__WEBHOOK_SECRET	Stripe endpoint
Shopify webhook secret	(per-shop, DB)	integration_configs.config.webhook_secret	Shopify endpoint

YouTube does not need a secret (see caveat above). Twitch uses the Helix OAuth tokens from channel_connections + app_credentials; no webhook secret is involved.

Permissions

Webhook handlers bypass Lumio's JWT/API-key auth and therefore bypass RBAC — they are trust-boundary protected by signature verification only. Once a payload is verified, the handler resolves the target account_id from the signed payload (channel_id, shop_domain, or Stripe customer/metadata) and writes events under that account. There is no webhooks:* permission.

Troubleshooting

• 401 Unauthorized on Kick / Trovo / Shopify / Stripe — signature mismatch. Confirm the secret in config matches the one configured on the platform dashboard and that the reverse-proxy in front of Lumio is not rewriting the raw body (HMAC is computed over req.body bytes; any middleware that re-serialises JSON breaks verification).
• 400 Bad Request on YouTube — Atom XML failed to parse or did not contain <yt:channelId>. Check that the topic URL you used when subscribing matches the channel you expect notifications for.
• Events not arriving in the dashboard — the endpoint may be returning 200 silently when no matching channel_connections row is found (see warn!("No account found for \{platform\} channel") log lines). Verify the channel is connected and that platform_channel_id matches exactly.
• Duplicate events — the event pipeline deduplicates by external_id (Kick / Trovo event_id, YouTube video_id, Shopify order/product ID). Duplicates are logged at debug! and silently acknowledged with 200.
• Dead PubSubHubbub subscriptions — YouTube leases expire (typically ≤10 days). If you stop receiving notifications, check the channel-sync worker is alive and has resubscribed; you can force a resubscribe by disconnecting and reconnecting the YouTube channel.
• Replay attacks — the handlers do not currently pin a max clock skew on the Stripe t= timestamp or reject duplicate event_ids at the HTTP layer. Stripe's own dedup (idempotent event IDs) and the event pipeline's external_id unique index absorb replays in practice, but treat this as defence-in-depth only.

Related

• Three-protocol architecture: API Reference → REST, GraphQL, WebSocket
• Events feature — how inbound events are normalised and broadcast once a webhook has been processed.
• Token Refresh — how the OAuth tokens that back webhook subscriptions are kept fresh.