Configuration
Configure Herald from your dashboard. Most settings are available under account settings, with engine toggles and webhook configuration on dedicated pages.
Engines
The core transport is always active. Chat and presence engines can be enabled or disabled per account from the dashboard.
| Engine | Default | Adds |
|---|---|---|
| Transport | Always on | Streams, events, subscribe, replay, ack mode, ephemeral events |
| Chat | Off | Edit, delete, reactions, cursors, typing, blocking |
| Presence | Off | Manual overrides, expiry, watchlist, batch queries |
Webhooks
Herald delivers webhooks to your app for every event, member change, and stream deletion. Configure the webhook URL and signing secret in the dashboard under Settings → Webhooks.
Webhooks are signed with HMAC-SHA256. The signature header includes a timestamp to prevent replay attacks:
signature = HMAC-SHA256(secret, timestamp + "." + body)
// Compare against the X-Herald-Signature headerWebhook events
| Event | Description |
|---|---|
event.new | A new event was published to a stream |
event.edited | An event body was edited |
event.deleted | An event was deleted |
member.joined | A user was added to a stream |
member.left | A user was removed from a stream |
stream.deleted | A stream was deleted |
You can filter which event types trigger webhooks. An empty filter delivers all types.
Delivery
Webhooks retry up to 3 times with exponential backoff on failure. The timeout per attempt is 5 seconds. Failed deliveries are logged in the dashboard.
Token settings
| Setting | Default | Description |
|---|---|---|
| Token TTL | 3600s (1 hour) | How long a WebSocket connection token is valid |
| Token warning | 60s | Seconds before expiry to send system.token_expiring |
Presence settings
| Setting | Default | Description |
|---|---|---|
| Linger period | 10s | Delay before broadcasting offline after disconnect |
| Override TTL | 4 hours | Default expiry for manual presence overrides |
| Heartbeat interval | 30s | WebSocket ping interval |
| Heartbeat timeout | 10s | Pong deadline before connection is dropped |
API key scoping
API keys can be scoped to read-only access. Read-only keys can query streams, members, events, and presence but cannot create, update, or delete resources. Configure key scopes when creating keys in the dashboard.
For self-hosted configuration
If you run Herald on your own infrastructure, server-level configuration (ports, storage, TLS) is managed via TOML config file and environment variables. See Self-Hosted.