Publish

The endpoint

POST /api/channels/:channel/publish

Capability: publish on that channel.

{
  "name": "order.created",
  "data": { "id": 7 }
}

Both fields are optional. name is the event name subscribers filter on; data is any JSON.

Response

{ "channel": "orders:new", "published": true }

curl

curl -X POST "$BLACKEVIN/api/channels/orders%3Anew/publish" \
  -H "authorization: $AUTH" \
  -H "content-type: application/json" \
  -d '{"name":"order.created","data":{"id":7}}'

The channel is a path segment, so : must be %3A. Unencoded, it addresses a different channel and succeeds — which is worse than failing.

SDK

const rest = new Blackevin.Rest({ key: process.env.BLACKEVIN_KEY });

await rest.channels.get('orders:new').publish('order.created', { id: 7 });

Encoding is handled for you.

From Ruby

There is no Ruby SDK yet. The call is small enough to write:

Net::HTTP.post(
  URI("#{ENV.fetch('BLACKEVIN_REST_URL')}/api/channels/orders%3Anew/publish"),
  { name: "order.created", data: { id: 7 } }.to_json,
  "content-type" => "application/json",
  "authorization" => "Basic #{Base64.strict_encode64(ENV.fetch('BLACKEVIN_ACCESS_KEY'))}"
)

The Basic value is the key verbatim — see the overview.

What it does downstream

A REST publish goes through the same fanout a socket publish does. Subscribers receive it, it is written to history, and it reaches the account's AMQP queues and every configured integration identically. Nothing about the message says it arrived over HTTP.

That is what makes this the right way to bridge into Blackevin: a job, a cron, or a third-party webhook arriving at your server can publish without opening a connection or pretending to be a client.

When it fails

{ "error": "…" } in the body, on all three.