Realtime REST publish and request signing

The Event Creator screen publishes through the ClutchCall control plane, which signs nothing you have to think about. The Equivalent cURL card on that screen shows the other path: a direct, signed POST to the engine’s HTTP plane, which is what your own server code does. That request carries five query parameters — auth_key, auth_timestamp, auth_version, body_md5 and auth_signature — and the engine rejects it if the signature does not match. This page documents how to build that request by hand, and what the queued result on the API response card means.

The publish endpoint and its query parameters

POST https://<ws-host>/apps/<app_id>/events

<ws-host> and <app_id> are filled in for you in the cURL card — the app id is also shown in the pill next to the page title.

Parameter	Value
`auth_key`	Your app key. Find it, with the matching secret, in Apps & keys.
`auth_timestamp`	Unix time in seconds. The cURL card generates it with `$(date +%s)`.
`auth_version`	`1.0`.
`body_md5`	Hex MD5 of the exact request body. See below.
`auth_signature`	Hex HMAC-SHA256 over the sign-string, keyed with your app secret.

Content-Type is application/json. Only auth_signature is excluded from the material that gets signed; every other parameter above is part of it.

Request body and encoding the data field

The body is a JSON object with three fields:

{
  "name": "order.created",
  "channels": ["private-orders"],
  "data": "{\"id\":\"ord_8821\",\"total\":49,\"currency\":\"EUR\"}"
}

name — the event name. This is the name subscribers bind to.
channels — an array of channel names. The Event Creator publishes to one channel at a time, so the card emits a single-element array.
data — a JSON-encoded string, not a nested object. The Data textarea in the console holds a JSON object; the card serialises that object and puts the resulting string in data. Client-side, the payload is parsed back out of that string.

If you build the request in your own code, the equivalent of what the card does is JSON.stringify(payload) for the data field, then JSON.stringify again for the whole envelope.

Computing body_md5

body_md5 is the lowercase hex MD5 digest of the serialised request body — the same bytes you pass to -d. Compute it after you have finished building the body; any whitespace or key-order change invalidates it.

import { createHash } from "node:crypto";

const body = JSON.stringify({
  name: "order.created",
  channels: ["private-orders"],
  data: JSON.stringify({ id: "ord_8821", total: 49.0, currency: "EUR" }),
});

const bodyMd5 = createHash("md5").update(body, "utf8").digest("hex");

Because the digest covers the body, you cannot reuse a signature across two publishes even if the channel and event are identical.

Building the sign-string and the auth_signature HMAC

The sign-string is three lines joined with a single \n (no trailing newline):

POST
/apps/<app_id>/events
auth_key=<key>&auth_timestamp=<unix_seconds>&auth_version=1.0&body_md5=<hex_md5>

Line by line:

The HTTP method, uppercase: POST.
The request path only — no scheme, no host, no query string.
The query parameters, excluding auth_signature, sorted by parameter name and joined with &. Use the raw values here, not URL-encoded ones.

Sorted by name, the four parameters always come out in the order shown above: auth_key, auth_timestamp, auth_version, body_md5. If you add any other query parameter, it has to be folded into the same sorted list. auth_signature is then the lowercase hex HMAC-SHA256 of that sign-string, keyed with your app secret:

import { createHmac } from "node:crypto";

const appId = "<app_id>";
const key = "<app_key>";
const secret = "<app_secret>";
const ts = Math.floor(Date.now() / 1000);

const query = [
  `auth_key=${key}`,
  `auth_timestamp=${ts}`,
  `auth_version=1.0`,
  `body_md5=${bodyMd5}`,
].join("&");

const signString = ["POST", `/apps/${appId}/events`, query].join("\n");
const signature = createHmac("sha256", secret).update(signString, "utf8").digest("hex");

const url = `https://<ws-host>/apps/${appId}/events?${query}&auth_signature=${signature}`;

Send the request with that URL and the exact body string you hashed:

curl -X POST "$URL" -H "Content-Type: application/json" -d "$BODY"

The app secret only ever lives on your server. It is the key to the HMAC and is never transmitted.

Channel and event name rules

The console validates the same shapes the control plane enforces, so a name that the Event Creator rejects will not work over REST either:

Channel name — required, at most 164 characters, and may contain only letters, digits and _ - = @ , . ;. This is the realtime protocol’s channel grammar: a stock client refuses to subscribe to anything outside it, so publishing to such a name publishes into the void.
Event name — required, at most 200 characters.

Channel prefixes are not restricted on the publish side. private- and presence- channels are legitimate publish targets, because a signed REST caller (or the console’s control plane) is an authorized publisher. The prefix governs who may subscribe, not who may publish.

Response codes and error bodies

A successful publish returns a 2xx and the console shows the green ok pill with the event and channel name. When the engine rejects the publish, the control plane surfaces the engine’s HTTP status and its response body unchanged. On the API response card that appears as a warning pill carrying the status code, the line Publish failed (HTTP <status>), and the raw response body rendered as JSON underneath. Read that body — it is the engine’s own error, not a control-plane wrapper, so it is the same text your server SDK would see from a direct signed call. Two failure modes never reach the engine at all:

Invalid JSON in the Data field. The console parses the textarea before sending and reports Invalid JSON: <message> inline. The Data field’s valid JSON / invalid indicator tracks this as you type.
Shape validation. An empty or malformed channel or event name is reported under the field and the request is not sent.

Accepted-but-queued delivery semantics

Publishes issued from the console do not go over the signed HTTP plane. The control plane pushes the publish body onto the engine’s generic ring buffer — clutchcall:realtime:ring, the same bus the presence and assist bridges ride. That is why console publishing needs no per-deployment HTTP configuration: the publisher is always reachable, even when the engine is not. The consequence is a third outcome besides success and failure. The response carries a wired flag:

Result	Pill	Meaning
`ok`, `wired: true`	`ok`	The event was handed to a heartbeating engine and fanned out across the edge mesh.
`ok`, `wired: false`	`queued`	The event was accepted onto the publish ring, but no engine is heartbeating right now.
`ok: false` + `status`	status	The engine rejected the publish. The status and body are shown verbatim.

queued is an acceptance, not an error: the card reads “Queued — engine offline; will deliver when the engine reconnects.” The event sits on the ring and is delivered when an engine comes back and drains it. Subscribers that are connected at that later moment receive it then; the publish is not replayed to clients that were subscribed at the original publish time and have since gone away. Treat queued as a signal to check engine health before you interpret a silent client as a publishing bug. If you see queued for a publish that you expected to be live, the event is not lost — the engine link is down.

Publishing from the console instead of signing

For one-off tests, the Event Creator is the shorter path: it publishes through the control plane with your org credentials, so there is no auth_key, body_md5 or HMAC to build, and private- / presence- channels work without extra setup. Use the signed REST endpoint when the publisher is your own backend, and reach for the Equivalent cURL card to get a copy-paste starting point that already mirrors the channel, event and payload you typed into the form.

Authentication — where app keys and secrets sit relative to client tokens
Telemetry — the metric and trace streams that cover publishes

Start here

Console

Guides

Reference

Realtime REST publish and request signing

The publish endpoint and its query parameters

Request body and encoding the data field

Computing body_md5

Building the sign-string and the auth_signature HMAC

Channel and event name rules

Response codes and error bodies

Accepted-but-queued delivery semantics

Publishing from the console instead of signing

​The publish endpoint and its query parameters

​Request body and encoding the data field

​Computing body_md5

​Building the sign-string and the auth_signature HMAC

​Channel and event name rules

​Response codes and error bodies

​Accepted-but-queued delivery semantics

​Publishing from the console instead of signing

​Related

The publish endpoint and its query parameters

Request body and encoding the data field

Computing body_md5

Building the sign-string and the auth_signature HMAC

Channel and event name rules

Response codes and error bodies

Accepted-but-queued delivery semantics

Publishing from the console instead of signing

Related