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.
You configure your incoming webhooks in the
Integrations tab of the Ably dashboard:
- In the
Incoming Webhooks Setupsection, click the
Register a new webhook endpointbutton.
- Give your webhook a friendly name.
- Specify a new or existing Ably channel which is going to receive the incoming webhooks.
- Click the
Generate a URLbutton.
- 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:
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
messageId of the message that results from the inbound webhook:
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:
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:
Your code to receive the named message is:
Idempotent publishing is possible by including a unique message identifier in an
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: