# Channels

Receive webhooks with signature checks, dedupe and retry, and send messages from any server code, through one named Channel.

Hosts: Node, Docker, Cloudflare, Vercel.

Example connectors: Stripe, Slack, Teams, Your API.

You write each connector. Use Agent Channels for built-in chat integrations.

:hero-figure{name="channels"}

```ts [server/channels/stripe.ts] fragment
import { defineChannel, stripe } from 'vite-hub/channels'
import { sendQueue } from 'vite-hub/queue'

// The file name makes this the "stripe" Channel.
export default defineChannel({
  // Checks Stripe-Signature with STRIPE_WEBHOOK_SECRET
  adapter: stripe(),
  on: {
    // Runs once per Stripe event ID, after ViteHub stores it.
    // A failed Result retries the event.
    'checkout.session.completed': event =>
      sendQueue('fulfil', event.data),
  },
})
```

```ts [server/queues/fulfil.ts]
import type { StripeEvent } from 'vite-hub/channels'
import { defineQueue } from 'vite-hub/queue'

export default defineQueue<StripeEvent>(async ({ payload }) => {
  // Fulfil the order of payload.data.object
  console.log('fulfil', payload.data.object.id)
})
```

```ts [server/channels/slack.ts]
import { createSlackAdapter } from '@chat-adapter/slack'
import { slack } from 'vite-hub/agent/channels'
import { defineChannel } from 'vite-hub/channels'

// The Agent that lists "slack" answers its messages.
export default defineChannel({
  adapter: slack({ adapter: createSlackAdapter() }),
})
```

```ts [server/agents/support.ts]
import { defineAgent } from 'vite-hub/agent'

export default defineAgent({
  channels: ['slack'],
  driver: { model: 'openai/gpt-5.1-mini' },
})
```

```ts [server/api/deploys.post.ts] fragment
import { defineEventHandler } from 'h3'
import { useChannel } from 'vite-hub/channels/server'

export default defineEventHandler(async () => {
  // Send through the same Channel from any server code
  const [error, receipt] = await useChannel('slack')
    .send('Deploy finished.', { recipient: 'slack:C0123:' })
  // A failed send returns an error, not a throw
  if (error) throw error
  return receipt
})
```

:::framework{name="Nuxt"}
```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['vite-hub/nuxt'],
  vitehub: { host: 'node', agent: true, channels: true, queue: true },
})
```
:::
:::framework{name="Nitro"}
```ts [vite.config.ts]
import { nitro } from 'nitro/vite'
import { defineConfig } from 'vite'
import { vitehub } from 'vite-hub'

export default defineConfig({
  plugins: [vitehub({ host: 'node', agent: true, channels: true, queue: true }), nitro()],
})
```
:::
:::framework{name="Vite"}
```ts [vite.config.ts]
import { defineConfig } from 'vite'
import { vitehub } from 'vite-hub'

export default defineConfig({
  plugins: [vitehub({ host: 'node', agent: true, channels: true, queue: true })],
})
```
:::

### [One file for each connection](https://vitehub.dev/docs/channels/get-started)

Add a file to `server/channels`. Its name is the Channel name, for both directions.

### [Webhooks that run once](https://vitehub.dev/docs/channels/server-api#receive-webhooks)

ViteHub checks the signature, stores the delivery, drops repeats by delivery ID, and retries the target.

### [A target for each event](https://vitehub.dev/docs/channels/server-api#receive-webhooks)

Send an event to a handler, a Queue, a Workflow, or the Agent that lists the Channel.

### [Send from anywhere](https://vitehub.dev/docs/channels/server-api#send-a-message)

`useChannel(name).send()` returns `[undefined, receipt]` or `[error, undefined]`.

### [Start a trigger from code](https://vitehub.dev/docs/channels/server-api#start-a-trigger-from-code)

A Schedule starts a Channel trigger with the same delivery rules, without a fake webhook.

### [Logs without message text](https://vitehub.dev/docs/channels/server-api#send-a-message)

Each send logs when it starts and ends. The logs leave out the text and options.

A Channel is one connection to a platform, defined once in `server/channels/<name>.ts` with `defineChannel({ adapter, on })` from `vite-hub/channels`. Use it for both directions: inbound webhooks go to the `on` targets (a handler, a Queue or Workflow through a handler, or a `defineChannelTrigger()`), or to the Agent that lists the Channel in `defineAgent({ channels: ['name'] })`. Outbound messages go through `useChannel(name).send()` from any server code. `sendChannelTrigger(name, trigger, input)` starts a trigger from code, such as a Schedule, with the same delivery rules as a webhook.

Use `stripe()` or `webhook({ signature, secret })` from `vite-hub/channels` for HTTP senders, and `slack()`, `teams()`, `discord()`, `telegram()`, `github()`, or `gmail()` from `vite-hub/agent/channels` for chat, forge, and mail. Inbound Channels need `agent: true` next to `channels: true`. Keep secrets in Server Env and never parse or verify a webhook by hand. To only check the signature in a plain route, without Agents, use `verifyWebhook(event, { provider: 'stripe', secret: 'STRIPE_WEBHOOK_SECRET' })` from `vite-hub/env`.

Prove one signed delivery reaching its target, one duplicate that does not run twice, and one outbound send with its receipt.

<!-- vitehub-docs:section-links -->
## In this section

- [Overview](https://vitehub.dev/raw/docs/channels.md) (this page)
- [Get started](https://vitehub.dev/raw/docs/channels/get-started.md)
- [Server API](https://vitehub.dev/raw/docs/channels/server-api.md)
- [Agent capability](https://vitehub.dev/raw/docs/channels/agent-capability.md)

Next: [CHANNELS_R0002](https://vitehub.dev/raw/docs/channels/diagnostics/channels_r0002.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
