Incoming Webhooks

While it is possible for external services to publish messages to Ably channels using the REST API and your existing API key and secret, an alternative method is to use incoming webhooks. Incoming webhooks provide a convenient way to configure Ably to integrate with external web services. The incoming webhooks are published to Ably channels as unenveloped messages.

Many web services generate webhooks as a way of communicating with your web application. These web services often generate webhooks based on interaction with their APIs and infrastructure. To allow Ably to receive these webhooks you need to configure the external web service with a webhook URL. The webhook URL specifies the endpoint for the generated webhook requests, and is defined from within the Ably dashboard.

You can configure the external web service with an Ably URL and webhook requests are invoked on that endpoint. The webhook data is published to the configured Ably channel as a message.

Ably also supports outgoing webhooks. These are webhooks that can be generated by Ably to integrate Ably with other services such as Zapier.

You configure your incoming webhooks in the Integrations tab of the Ably dashboard:

1. In the Incoming Webhooks Setup section, click the Register a new webhook endpoint button.
2. Give your webhook a friendly name.
3. Specify a new or existing Ably channel which is going to receive the incoming webhooks.
4. Click the Generate a URL button.
5. Copy the generated webhook URL to the clipboard, and use it to configure your service as required.

You can optionally test your webhook is correctly configured using the Curl requests provided in the dashboard.

You can now optionally test your incoming webhook with a Curl command such as the following:

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"}'

Copy
Copied!

This Curl request is equivalent to how an external service would publish a webhook. Note that incoming webhooks are simply REST publishes, and so they reflect the functionality of the REST publish API.

Ably responds with the channel and messageId of the message that results from the inbound webhook:

{
	"channel": "webhook-test",
	"messageId": "4RcVBJsAbC:0"
}

Copy
Copied!

A successful publish responds with a 201 statusCode; failure results in a 4xx or 5xx code and an ErrorInfo response body.

You can receive the incoming webhook as you would a normal Ably message on a channel. For example, if the incoming webhook data is in JSON format, you can display the data using the following code:

Node.js
Select...

var ably = new require("ably").Realtime('{{API_KEY_NAME}}:{{API_KEY_SECRET}}');


/* Obtain the channel that has been configured to receive webhooks */
var channel = ably.channels.get('webhook-test');


/* Incoming webhook messages can be displayed using this function */
channel.subscribe((message) => {
    console.log("webhook: " + JSON.stringify(message.data));
});

Copy
Copied!

The request body of incoming webhooks is treated as a message to be published. You can optionally set headers and parameters in your external service, if the service supports this, as described in the REST API documentation.

The following example shows how the message name could be set via a request 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'

Copy
Copied!

Your code to receive the named message is:

Node.js
Select...

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

Copy
Copied!

Idempotent publishing is possible by including a unique message identifier in an X-Ably-MessageId header.

Rate-limiting is applied to webhook message publishes, as with REST publishes.

Ably’s incoming webhooks support provides a convenient way to configure external services to work with Ably. The incoming webhooks are published as messages on the configured Ably channel, where they can be processed by your application as required.

See also the following resources for further information:

• Ably dashboard
• Outgoing webhooks
• Unenveloped messages
• Introduction to idempotent publishing