AWS Lambda Functions

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

AWS Lambda Functions provide event-driven serverless compute functions which allow users to easily run code whenever events are sent to it. These can be very useful for integrating into various other AWS systems.

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

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

AWS Region

The region you chose for your AWS Lambda function.

Function Name

The name you gave your AWS Lambda function.

AWS Authentication Scheme

the authentication scheme you use for your function. Either AWS Credentials or ARN of an assumable role. See the Ably AWS authentication documentation.

Qualifier

optional qualifier for your AWS Lambda function.

Source

Choose which of channel.message, channel.presence, channel.lifecycle, or channel.occupancy events on channels should activate this event rule.

Channel filter

An optional filter on channel name, to restrict the channels the rule applies to. Use a regular expression to match multiple channels.

At present, it is not possible to batch messages to AWS Lambda Functions, nor can messages be encoded in anything besides JSON.

Each enveloped message will have the following fields:

source

the source for the webhook, which will be one of channel.message, channel.presence, channel.lifecycle, or channel.occupancy

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.

For message events, the messages array contains a raw message.

The following is an example of an enveloped message payload:

{
  "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"
  }]
}

Copy
Copied!

Messages sent over the realtime service are automatically decoded into Message objects by the Ably client library. With webhooks you need to to do this explicitly, using Message.fromEncodedArray on the messages array, or Message.fromEncoded on an individual member of that array. This will transform them into an array of Message objects (or in the case of fromEncoded, an individual Message). This has several advantages, e.g.:

• It will fully decode any data (using the encoding) back into the same datatype that it was sent in (or an equivalent in each client library’s language)
• If you are using encryption, you can pass your encryption key to the method and it will decrypt the data for you

We recommend you do this for all messages you receive over webhooks. For example (using ably-js):

JavaScript
Select...

const messages = Ably.Realtime.Message.fromEncodedArray(item.messages);
messages.forEach((message) => {
  console.log(message.toString());
})

Copy
Copied!

For presence events, the presence array contains a raw presence message.

The following is an example of of an enveloped message payload with a presence array:

{
  "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
  }]
}

Copy
Copied!

Presence messages sent over the realtime service are automatically decoded into PresenceMessage objects by the Ably client library. With webhooks you need to to do this explicitly, using PresenceMessage.fromEncodedArray on the presence array, or PresenceMessage.fromEncoded on an individual member of that array. This will transform them into an array of PresenceMessage objects (or in the case of fromEncoded, an individual PresenceMessage). This has several advantages, e.g.:

• It will decode the (numerical) action into a Presence action string (such as enter update or leave
• It will fully decode any data (using the encoding) back into the same datatype that it was sent in (or an equivalent in each client library’s language)
• If you are using encryption, you can pass your encryption key to the method and it will decrypt the data for you

We recommend you do this for all presence messages you receive over webhooks. For example (using ably-js):

JavaScript
Select...

const messages = Ably.Realtime.PresenceMessage.fromEncodedArray(item.messages);
messages.forEach((message) => {
  console.log(message.toString());
})

Copy
Copied!

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 "<loading API key, please wait>" \
          -H "Content-Type: application/json" \
          --data '{ "name": "publish", "data": "example" }'

API Key:
Demo Only
Copy
Copied!

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

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:

JavaScriptNode.js
Select...

realtime = new Ably.Realtime({
  key: '<loading API key, please wait>',
  clientId: 'bob'
});
channel = realtime.channels.get('some_channel');
await channel.presence.enter('some data');

API Key:
Demo Only
Copy
Copied!

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”.