Webhooks

Stripe Webhooks

POST /api/webhooks/stripe

Handles Stripe subscription lifecycle events. The endpoint verifies the webhook signature using STRIPE_WEBHOOK_SECRET before processing.

Events Handled

Event	Action
`checkout.session.completed`	Creates/updates subscription, sets plan, notifies admin
`invoice.payment_succeeded`	Updates subscription period end date
`customer.subscription.updated`	Updates plan and period end date
`customer.subscription.deleted`	Resets plan to STARTER, clears subscription data
`invoice.payment_failed`	Notifies admin with failure details

Error Handling

If processing fails, the endpoint returns HTTP 500 so Stripe retries the webhook. This prevents silent data loss from transient database errors.

Local Development

Use the Stripe CLI to forward webhooks to your local server:

stripe listen --forward-to localhost:3000/api/webhooks/stripe

The CLI prints a webhook signing secret — set it as STRIPE_WEBHOOK_SECRET in your .env.

Environment Variables

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_STARTER_PRICE_ID=price_...
STRIPE_PRO_PRICE_ID=price_...
STRIPE_ENTERPRISE_PRICE_ID=price_...

HubSpot Webhooks

POST /api/webhooks/hubspot

Handles outgoing messages from HubSpot's Custom Channels integration. When a HubSpot user replies to a Telegram conversation from the HubSpot Inbox, HubSpot sends a webhook to this endpoint.

Event Types

Type	Action
`OUTGOING_CHANNEL_MESSAGE_CREATED`	Forwards the message to the corresponding Telegram conversation via GramJS

Current Status

This endpoint is a placeholder for the Custom Channels feature (Pro tier). It accepts webhooks and logs them but does not yet forward messages to Telegram. The two-way messaging feature is on the roadmap.

Admin Notifications

Conduits uses a separate Telegram Bot API bot (not MTProto) to send operational alerts to a private chat. This is not a webhook endpoint — it's an outbound notification system.

Alert Levels

Level	Use
`info`	Sync completions, user signups, connections
`warn`	Partial sync failures, high failure rates, FloodWaitErrors
`error`	Complete sync failures, session expirations, API errors
`revenue`	New subscriptions, cancellations, payment failures, upgrades

Setup

Create a bot via @BotFather
Start a conversation with your bot
Get your chat ID from the /getUpdates endpoint
Set environment variables:

ADMIN_TELEGRAM_BOT_TOKEN=7123456789:AAH...
ADMIN_TELEGRAM_CHAT_ID=123456789

Where Alerts Fire

Sync pipeline — completion, partial failure, full failure, FloodWaitError, session expiration
Stripe webhooks — new subscription, cancellation, payment failure, upgrade
HubSpot client — API errors, token refresh failures
AI summarizer — non-JSON responses, API errors
Heartbeat job — every 15 minutes if issues detected, daily summary at 8 AM UTC