Cloudflare Workers

As part of Reactor Events, it is possible to integrate with various systems.

Cloudflare Workers allow you to make use of Cloudflare’s Edge Network to distribute your normal JavaScript-based functions.

Tutorials & Examples

If you would like to just dive in and see an example of this being implemented, then take a look at our Cloudflare Worker tutorial.

For more details on the specifics of how Reactor Events and our integrations work, check out our Reactor Events documentation.

Rule fields

URL
The URL of your Clouflare Worker
Custom headers
Optionally allows you to provide a set of headers that will be included in all HTTP POST requests. You must use format "XCustom-Header-1:value1" for each header you add
Source
Choose which of Message, Presence, or Channel Lifecycle events on channels should activate this Reactor Event Rule. Channel Lifecycle events are only available in Batch Request mode
Request Mode
This will either be in Single Request mode or Batch Request mode. Single Request will send each event as separately to the endpoint specified by the Rule. Batch Request will send events triggered concurrently in the same request
Channel filter
An optional filter, which allows the Rule to be applied to a restricted set of channels. This can be specified as a regular expression, allowing for swathes of channels to be used
Encoding
The encoding to be used by this Rule. This can be either JSON or MsgPack


If the Rule is in the Single Request mode, it will also have the following options:

Enveloped
If the rule has the Enveloped option set, then data delivered by this Rule will be wrapped in an Ably envelope. Otherwise, the Rule will send the raw payload


If the Rule is in the Batch Request mode, it will have the following additional options:

Sign with key
Ably will optionally sign the data with the specified private key. This will be included as an HTTP header X-Ably-Signature in every HTTP post request issued to your server. See webhook security for more details.

Examples

Given the various potential combinations of enveloped, batched and message sources, it can be good to know what to expect given certain combinations of rules.

Batched event payloads

Batched events will have the following headers:

content-type
the type of the payload. This can be either application/json, text/plain, or application/octet-stream, depending on if it’s JSON, text, or binary respectively
x-ably-envelope-appid
the app ID which the message came from
content-type
the type of the payload. This will be application/json or application/x-msgpack
x-ably-version
the version of Reactor Event. At present this should be 1.2

Each batched message will have the following fields:

name
the event type, aka “presence.message”, “channel.message”, “channel.closed”, etc
webhookId
an internal unique ID for the configured webhook
source
the source for the webhook, namely “channel.message”, “channel.presence”, “channel.lifecycle
timestamp
a timestamp represented as milliseconds since the epoch for the presence event
data
an object containing the data of the event defined below in JSONPath format

Batched message events

For message events, data will contain:

data.channelId
name of the channel that the presence event belongs to
data.site
an internal site identifier indicating which primary datacenter the member is present in
data.messages
an Array of Message
{
  "items": [{
    "webhookId": "ABcDEf",
    "source": "channel.lifecycle",
    "timestamp": 1562124922426,
    "serial": "a7bcdEFghIjklm123456789:4",
    "name": "channel.message",
    "data": {
      "channelId": "channelName",
      "site": "eu-west-1-A",
      "messages": [{
        "id": "ABcDefgHIj:1:0",
        "connectionId": "ABcDefgHIj",
        "timestamp": 1123145678900,
        "data": "some message data",
        "name": "my message name"
      }]
    }
  }]
}

Batched presence events

For presence events, data will contain:

data.channelId
name of the channel that the presence event belongs to
data.site
an internal site identifier indicating which primary datacenter the member is present in
data.presence
an Array of Presence events
{
  "items": [{
    "webhookId": "ABcDEf",
    "source": "channel.lifecycle",
    "timestamp": 1562124922426,
    "serial": "a7bcdEFghIjklm123456789:4",
    "name": "presence.message",
    "data": {
      "channelId": "education",
      "site": "eu-west-1-A",
      "presence": [{
        "id": "ABcDefgHIj:1:0",
        "connectionId": "ABcDefgHIj",
        "timestamp": 1123145678900,
        "clientId": "bob",
        "data": "some message data",
        "action": 4
      }]
    }
  }]
}

Batched channel lifecycle events

For channel lifecycle events, data will contain:

data.channelId
name of the channel that the presence event belongs to
data.status
a ChannelStatus object
{
  "items": [{
    "webhookId": "ABcDEf",
    "source": "channel.lifecycle",
    "timestamp": 1562124922426,
    "serial": "a7bcdEFghIjklm123456789:4",
    "name": "channel.opened",
    "data": {
      "channelId": "channelName",
      "name": "channelName",
      "status": {
        "isActive": true,
        "occupancy": {
          "metrics": {
            "connections": 1,
            "publishers": 1,
            "subscribers": 1,
            "presenceConnections": 1,
            "presenceMembers": 0,
            "presenceSubscribers": 1
          }
        }
      }
    }
  }]
}

Enveloped event payloads

Enveloped events will have the following headers:

content-type
the type of the payload. This can be either application/json, text/plain, or application/octet-stream, depending on if it’s JSON, text, or binary respectively
x-ably-version
the version of Reactor Event. At present this should be 1.2
x-ably-envelope-appid
the app ID which the message came from
content-type
the type of the payload. This will be application/json or application/x-msgpack for enveloped messages

Each enveloped message will have the following fields:

source
the source for the webhook, namely “channel.message” or “channel.presence
appId
the Ably app this message came from
channel
the Ably channel where the event occurred
site
the Ably datacenter which sent the message
timestamp
a timestamp represented as milliseconds since the epoch for the presence event

In addition, it will contain another field which will contain the actual message, which is named according to the message type.

Enveloped message events

For message events, there will be a messages field, which will contain the Message event.

{
  "source": "channel.message",
  "appId": "aBCdEf",
  "channel": "channel-name",
  "site": "eu-central-1-A",
  "ruleId": "1-a2Bc",
  "messages": [{
    "id": "ABcDefgHIj:1:0",
    "connectionId": "ABcDefgHIj",
    "timestamp": 1123145678900,
    "data": "some message data",
    "name": "my message name"
  }]
}

Enveloped presence events

For presence events, there will be a presence field, which will contain the Presence event.

{
  "source": "channel.message",
  "appId": "aBCdEf",
  "channel": "channel-name",
  "site": "eu-central-1-A",
  "ruleId": "1-a2Bc",
  "presence": [{
    "id": "abCdEFgHIJ:1:0",
    "clientId": "bob",
    "connectionId": "Ab1CDE2FGh",
    "timestamp": 1582270137276,
    "data": "some data in the presence object",
    "action": 4
  }]
}

Non-enveloped event payloads

Non-enveloped events have quite a few headers, in order to provide context to the data sent in the payload. These are:

content-type
the type of the payload. This can be either application/json, text/plain, or application/octet-stream, depending on if it’s JSON, text, or binary respectively
x-ably-version
the version of Reactor Event. At present this should be 1.2
x-ably-envelope-appid
the app ID which the message came from
x-ably-envelope-channel
the Ably channel which the message came from
x-ably-envelope-rule-id
the Ably Reactor Rule ID which was activated to send this message
x-ably-envelope-site
the Ably datacenter which sent the message
x-ably-envelope-source
the source for the webhook, namely “channel.message” or “channel.presence
x-ably-message-client-id
the client ID of the connection which sent the event
x-ably-message-connection-id
the connection ID responsible for the initial event
x-ably-message-id
the message’s unique ID
x-ably-message-timestamp
the time the message was originally sent

Non-enveloped message events

For message events, there will be the additional headers:

x-ably-message-name
The name of the Message

The payload will contain the data of the Message.

For example, if you sent the following curl message, which sends a JSON message to the channel my_channel:

curl -X POST https://rest.ably.io/channels/my_channel/messages \
          -u "xVLyHw.xc27LA:VrFS5KOGun0WB7l5" \
          -H "Content-Type: application/json" \
          --data '{ "name": "publish", "data": "example" }'

The x-ably-message-name header would be publish, and the payload would be example.

Non-enveloped presence events

For Presence events, there will be the additional headers:

x-ably-message-action
the action performed by the event (update, enter, leave)

The payload will contain the data of the Presence message.

For example, if a client enters a channel’s presence with the following code:

realtime = new Ably.Realtime({ key: 'xVLyHw.xc27LA:VrFS5KOGun0WB7l5', clientId: 'bob' });
channel = realtime.channels.get('some_channel');
channel.presence.enter('some data');
realtime = new Ably.Realtime({ key: 'xVLyHw.xc27LA:VrFS5KOGun0WB7l5', clientId: 'bob' });
channel = realtime.channels.get('some_channel');
channel.presence.enter('some data');

Then the x-ably-message-action would be enter, the x-ably-message-client-id would be “bob”, and the payload would be “some data”.


API reference
Documentation