Inbound webhooks

External services can publish messages to Ably channels using the REST API, however, a simpler alternative is to use incoming webhooks.

Many web services generate webhooks to communicate with applications. These webhooks are triggered based on interactions with their APIs or infrastructure. When a webhook request is received by Ably, its payload is published to a channel as an unenveloped message.

Ably also supports outbound webhooks, which send data from Ably to other external services such as AWS, Google Cloud Platform or Zapier.

Configure an incoming webhook

Set up incoming webhooks in the Integrations tab of the Ably dashboard:

  1. Click Register a new webhook endpoint.
  2. Name your webhook.
  3. Select an Ably channel to receive webhook messages.
  4. Click Generate a URL.
  5. Copy the generated URL and configure your external service with it.

Test incoming webhook

Run the following Curl command to simulate an incoming webhook request:

curl -X POST 'https://rest.ably.io/channels/webhook-test/messages?key={{API_KEY_NAME}}:{{API_KEY_SECRET}}&enveloped=false' \
     -H 'content-type: application/json' --data '{"some":"json"}'

Incoming webhooks function as REST publishes, meaning they follow the same behavior and functionality as the REST publish API.

Ably responds with the channel and messageId:

JSON

1

2

3

4

{
	"channel": "webhook-test",
	"messageId": "20xxxxxxx"
}

A successful request returns a 201 status. Failures return with an ErrorInfo response.

Receive webhook messages

Incoming webhooks publish messages to an Ably channel. You can subscribe to these messages using an Ably SDK:

JavaScript

1

2

3

4

5

6

7

8

const Ably = require("ably");

const ably = new Ably.Realtime('demokey:*****');
const channel = ably.channels.get('webhook-test');

channel.subscribe((message) => {
    console.log(`webhook received: ${JSON.stringify(message.data)}`);
});
API key:
DEMO ONLY

Optional headers

The request body of incoming webhooks is treated as a message to be published. If the external service allows, you can customize webhook requests by including optional headers and parameters.

The following example demonstrates how to set a message name using the X-Ably-Name header:

curl -X POST 'https://rest.ably.io/channels/webhook-test/messages?key=key:secret&enveloped=false' \
     -H 'content-type: application/json' --data '{"some":"json"}' \
     -H 'X-Ably-Name: webhook-message'

Then, filter messages by name:

JavaScript

1

2

3

channel.subscribe('webhook-message', (message) => {
    console.log("webhook: " + JSON.stringify(message.data));
});

To ensure that publishes are idempotent, add a unique X-Ably-MessageId header.

Select...