REALTIME EVENTS & NOTIFICATIONS API

Signal

Signal moves events from your backend to your users in real time — push a payload to a channel and every connected client receives it over a persistent connection, with delivery falling back to webhooks when no one's listening.

Base URL & authentication

Pass your API key on every request via the X-API-Key header. Realtime connections authenticate the same key as a query parameter during the WebSocket handshake.

Base URL

https://api.signal.dev/v1

Every request needs

X-API-Key: sig_live_••••••••

Channels

Named streams that clients subscribe to and you publish events into.

POST/channels

Create a channel

Creates a named channel. Channel names must be unique within your project and are used directly by clients when subscribing.

Body parameters

Name	Type	Description
`name`*	string	Unique channel identifier, e.g. "room-482".
`private`	boolean	If true, clients must present a per-user auth token to subscribe. Defaults to false.

Request

curl -X POST https://api.signal.dev/v1/channels \
  -H "X-API-Key: sig_live_••••••••" \
  -d name="room-482"

Response

{
  "id": "chn_5b91f0",
  "name": "room-482",
  "private": false,
  "created_at": "2026-05-02T18:11:00Z"
}

GET/channels

List channels

Returns every channel in your project, with current subscriber counts.

Request

curl https://api.signal.dev/v1/channels \
  -H "X-API-Key: sig_live_••••••••"

Response

{
  "data": [
    { "id": "chn_5b91f0", "name": "room-482", "subscribers": 14 }
  ]
}

Events

Publish payloads into a channel for connected clients to receive.

POST/events

Publish an event

Publishes an event to a channel. Connected clients receive it within milliseconds; if nobody's subscribed, it's dropped unless `persist` is set.

Body parameters

Name	Type	Description
`channel`*	string	Name of the target channel.
`type`*	string	Event type clients use to route the payload, e.g. "message.created".
`payload`*	object	Arbitrary JSON delivered to subscribers as-is.
`persist`	boolean	Store the event so late subscribers can replay it. Defaults to false.

Request

curl -X POST https://api.signal.dev/v1/events \
  -H "X-API-Key: sig_live_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "room-482",
    "type": "message.created",
    "payload": { "text": "hey" }
  }'

Response

{
  "id": "evt_28d4a7",
  "channel": "room-482",
  "delivered_to": 14,
  "published_at": "2026-05-02T18:12:41Z"
}

Realtime

Open a persistent connection to receive events as they're published.

GET/realtime/connect

Open a realtime connection

Upgrades to a WebSocket connection. Subscribe to one or more channels after connecting by sending a `{ "action": "subscribe", "channel": "..." }` frame.

Query parameters

Name	Type	Description
`key`*	string	Your API key, passed as a query param during the handshake.

Request

const ws = new WebSocket(
  `wss://api.signal.dev/v1/realtime/connect?key=${SIGNAL_KEY}`
)

ws.onopen = () => {
  ws.send(JSON.stringify({ action: "subscribe", channel: "room-482" }))
}

ws.onmessage = (msg) => {
  const event = JSON.parse(msg.data)
  console.log(event.type, event.payload)
}

Response

// Frame received after subscribing
{
  "channel": "room-482",
  "type": "message.created",
  "payload": { "text": "hey" },
  "published_at": "2026-05-02T18:12:41Z"
}