Herald

Quickstart

Create an account, get your API credentials, create a stream, and publish your first event. This takes about two minutes.

1. Create an account

Sign up at herald.skeptik.io. Once your account is created, you land in the dashboard where you can manage streams, view connections, and configure webhooks.

2. Get your API credentials

In the dashboard, go to API Keys and create a new key. You get a key and secret pair. The key identifies your account. The secret signs WebSocket connection tokens and authenticates HTTP API calls.

3. Create a stream

Streams are named channels that users subscribe to. Create one with the HTTP API:

curl -X POST https://herald.skeptik.io/v1/streams \
  -u "YOUR_KEY:YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "general", "meta": {}}'

You can also create streams from the dashboard under Streams.

4. Add a member

curl -X POST https://herald.skeptik.io/v1/streams/STREAM_ID/members \
  -u "YOUR_KEY:YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "alice", "role": "member"}'

5. Connect over WebSocket

Herald authenticates WebSocket connections with HMAC-SHA256 signed tokens. Your backend generates a token for each user, then the client connects:

wss://herald.skeptik.io/ws?key=YOUR_KEY&token=SIGNED_TOKEN&user_id=alice&streams=STREAM_ID

On success, Herald responds with an auth_ok frame. The SDKs handle token generation and connection management — see SDKs for language-specific setup.

6. Publish an event

// Send over WebSocket:
{
  "type": "event.publish",
  "ref": "1",
  "payload": {
    "stream_id": "STREAM_ID",
    "type": "message",
    "body": {"text": "Hello from Herald"},
    "meta": {}
  }
}

Herald assigns a sequence number, stores the event, fans it out to all subscribers, and responds with an event.ack containing the event ID and sequence.

Next steps

  • Architecture — fan-out, storage, presence, and integration patterns
  • WebSocket Protocol — frame types, reconnect, ack mode
  • SDKs — browser and server-side client libraries
  • Self-Hosted — run Herald on your own infrastructure