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.
Tutorials
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.
Rule fields
- 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
orARN 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
, orchannel.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.
Restrictions
At present, it is not possible to batch messages to AWS Lambda Functions, nor can messages be encoded in anything besides JSON.
Examples
Enveloped event payloads
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
, orchannel.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.
Enveloped message events
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"
}]
}
CopyCopied!
Decoding enveloped messages
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 theencoding
) 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):
const messages = Ably.Realtime.Message.fromEncodedArray(item.messages);
messages.forEach((message) => {
console.log(message.toString());
})
CopyCopied!
Enveloped presence events
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
}]
}
CopyCopied!
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 asenter
update
orleave
- It will fully decode any
data
(using theencoding
) 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):
const messages = Ably.Realtime.PresenceMessage.fromEncodedArray(item.messages);
messages.forEach((message) => {
console.log(message.toString());
})
CopyCopied!
Non-enveloped event payloads
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 "<loading API key, please wait>" \
-H "Content-Type: application/json" \
--data '{ "name": "publish", "data": "example" }'
Demo OnlyCopyCopied!
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:
realtime = new Ably.Realtime({
key: '<loading API key, please wait>',
clientId: 'bob'
});
channel = realtime.channels.get('some_channel');
await channel.presence.enter('some data');
Demo OnlyCopyCopied!
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”.