EDU-2092: Adds Generic HTTP webhooks page #2847
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the ✨ Finishing touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
m-hulbert
reviewed
Sep 30, 2025
| meta_description: "Configure generic HTTP webhooks to trigger HTTP endpoints and notify external services when events occur in Ably." | ||
| meta_keywords: "ably webhooks, http webhooks, webhook integration, generic webhooks, webhook endpoints, event notifications, realtime webhooks" | ||
| redirect_from: | ||
| - /docs/integrations/webhooks/generic |
| index: true, | ||
| }, | ||
| { | ||
| name: 'Generic HTTP Webhooks', |
| 2. Click the **Integrations** tab. | ||
| 3. Click the **New Integration Rule** button. | ||
| 4. Choose **Webhook**. | ||
| 5. Choose **Generic HTTP Webhook**. |
There was a problem hiding this comment.
I think this is just 'Webhook' in the dashboard.
| | Request Mode | Choose between **Single request** (sends each event individually) or **Batch request** (groups multiple events into a single request). | | ||
| | Source | Choose which event types trigger the webhook: `channel.message`, `channel.presence`, `channel.lifecycle`, or `channel.occupancy`. | | ||
| | [Channel filter](/docs/platform/integrations/webhooks#filter) | Filters the source channels based on a regular expression. | | ||
| | [Enveloped](/docs/platform/integrations/webhooks#enveloped) | When enabled (default), messages are wrapped in additional metadata. When disabled, only the raw message data is sent. | |
There was a problem hiding this comment.
You're missing Sign with key and Encoding options here.
Comment on lines
+38
to
+111
| ## Webhook request format | ||
|
|
||
| There are two webhook request formats: single request and batch request. | ||
|
|
||
| ### Single request mode | ||
|
|
||
| When **Single request** mode is selected, a separate HTTP POST request is sent for each event. This is useful when your endpoint processes one event at a time or when you need immediate notification of each event. | ||
|
|
||
| The following example demonstrates request headers: | ||
|
|
||
| ``` | ||
| POST /webhook HTTP/1.1 | ||
| Host: your-endpoint.com | ||
| Content-Type: application/json | ||
| X-Ably-Message-Id: hKJ7FjEQh@1519124010003-0 | ||
| X-Ably-Message-Source: channel.message | ||
| X-Ably-Message-Action: message | ||
| User-Agent: Ably/1.0 | ||
| ``` | ||
|
|
||
| The following example is an enveloped payload: | ||
|
|
||
| ```json | ||
| { | ||
| "source": "channel.message", | ||
| "appId": "aBCdEf", | ||
| "channel": "channel-name", | ||
| "site": "eu-central-1-A", | ||
| "ruleId": "1-a2Bc", | ||
| "messages": [{ | ||
| "id": "ABcDefgHIj:1:0", | ||
| "clientId": "user-123", | ||
| "connectionId": "ABcDefgHIj", | ||
| "timestamp": 1582270137276, | ||
| "data": "Hello World", | ||
| "name": "greeting" | ||
| }] | ||
| } | ||
| ``` | ||
|
|
||
| The following example is a non-enveloped payload: | ||
|
|
||
| ``` | ||
| Hello World | ||
| ``` | ||
|
|
||
| ### Batch request mode | ||
|
|
||
| When **Batch request** mode is selected, multiple events occurring within a short timeframe are grouped into a single HTTP POST request. This reduces the number of requests and is more efficient for high-throughput scenarios. | ||
|
|
||
| The following example is a batched payload: | ||
| ```json | ||
| { | ||
| "items": [{ | ||
| "webhookId": "ABcDEf", | ||
| "source": "channel.message", | ||
| "serial": "a7bcdEFghAbcDef123456789:4", | ||
| "timestamp": 1562124922426, | ||
| "name": "channel.message", | ||
| "data": { | ||
| "channelId": "chat-channel-4", | ||
| "site": "eu-west-1-A", | ||
| "messages": [{ | ||
| "id": "ABcDefgHIj:1:0", | ||
| "clientId": "user-3", | ||
| "connectionId": "ABcDefgHIj", | ||
| "timestamp": 1123145678900, | ||
| "data": "the message data", | ||
| "name": "a message name" | ||
| }] | ||
| } | ||
| }] | ||
| } | ||
| ``` |
There was a problem hiding this comment.
There are some things here that don't quite make sense and this info should be covered by the generic section of the webhooks, so maybe drop it?
Comment on lines
+113
to
+121
| ## Next steps | ||
|
|
||
| For more advanced webhook configuration options and security features, see the [Outbound webhooks overview](/docs/platform/integrations/webhooks). | ||
|
|
||
| You may also want to explore other integration options: | ||
| - [Lambda Functions](/docs/platform/integrations/webhooks/lambda) for AWS Lambda integration | ||
| - [Azure Functions](/docs/platform/integrations/webhooks/azure) for Microsoft Azure integration | ||
| - [Message Queues](/docs/platform/integrations/queues) for reliable message processing | ||
| - [Streaming integrations](/docs/platform/integrations/streaming) for data pipeline integration |
There was a problem hiding this comment.
We don't have this for any of the other files, and I'm not sure it makes sense to point people to other integrations when they've chosen a specific type.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR:
https://ably.atlassian.net/browse/EDU-2071