From df759087ec4efcd7b4ccd051a2e8deb9535783c1 Mon Sep 17 00:00:00 2001 From: RajatPawar <18614743+RajatPawar@users.noreply.github.com> Date: Mon, 3 Aug 2026 16:14:05 -0700 Subject: [PATCH 1/5] docs(destinations): document Slack destinations (ENG-4113) - New Slack destinations page (setup via incoming webhook, how notifications and data are rendered). - List Slack in the destinations overview + nav, and in the notifications type list. Co-Authored-By: Claude Opus 4.8 --- src/destinations/overview.mdx | 3 ++- src/destinations/slack.mdx | 35 ++++++++++++++++++++++++++++++++++ src/docs.json | 1 + src/notifications/overview.mdx | 2 +- 4 files changed, 39 insertions(+), 2 deletions(-) create mode 100644 src/destinations/slack.mdx diff --git a/src/destinations/overview.mdx b/src/destinations/overview.mdx index ff42f2ae..7fa3179f 100644 --- a/src/destinations/overview.mdx +++ b/src/destinations/overview.mdx @@ -2,7 +2,7 @@ title: Overview --- -Ampersand currently supports webhook, Kinesis, and S3 destinations. Destinations allow you to route data synced from SaaS instances via [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions), and to receive real-time [Notifications](/notifications) about important lifecycle events in your projects. +Ampersand currently supports webhook, Slack, Kinesis, and S3 destinations. Destinations allow you to route data synced from SaaS instances via [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions), and to receive real-time [Notifications](/notifications) about important lifecycle events in your projects. ## Add a destination to the Ampersand Dashboard @@ -35,6 +35,7 @@ Destinations can also be used to receive [notifications](/notifications) about i ## Supported destinations * [Webhook destinations](/destinations/webhooks) +* [Slack destinations](/destinations/slack) * [Amazon Kinesis destinations](/destinations/kinesis) * [Amazon S3 destinations](/destinations/s3) diff --git a/src/destinations/slack.mdx b/src/destinations/slack.mdx new file mode 100644 index 00000000..255d4568 --- /dev/null +++ b/src/destinations/slack.mdx @@ -0,0 +1,35 @@ +--- +title: Slack destinations +--- + +For more information on destinations, see the [Destinations](/destinations) page. + +A Slack destination delivers messages to a Slack channel using a [Slack incoming webhook](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks). It's a great fit for [Notifications](/notifications) — for example, posting a message to your team's channel whenever a customer connects an integration or a sync runs into an error. + +## Setting up a Slack destination + +1. In Slack, [create a Slack app](https://api.slack.com/apps?new_app=1) (or use an existing one), enable **Incoming Webhooks**, and add a webhook to the channel you want Ampersand to post to. Slack gives you a URL that looks like `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX`. +2. In the [Ampersand Dashboard](https://dashboard.withampersand.com/projects/_/destinations), add a new destination of type **Slack** and paste in that URL. (The URL must be a `hooks.slack.com` URL.) + + +The Slack channel is fixed when you create the incoming webhook — Ampersand posts to that channel and cannot override it. + + +## What Ampersand posts to Slack + +Ampersand reshapes each message into Slack's format before sending it. + +### Notifications + +Notifications are rendered as a short, human-friendly sentence, followed by the raw notification payload for full detail. For example, a `connection.error` notification appears as: + +> ⚠️ Salesforce connection for Acme (ID `conn_123`) encountered an error: The refresh token is invalid or expired +> ``` +> {"notificationType":"connection.error","data":{ ... }} +> ``` + +Route notification events to a Slack destination the same way as any other destination — see the [Notifications overview](/notifications) for setup. + +### Read & subscribe data + +Data synced via [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions) is delivered as the JSON payload nested directly into the Slack message text. Because Slack renders message text as markdown, Slack destinations are best suited to notifications and low-volume data; for high-volume data delivery, use a [webhook](/destinations/webhooks), [Kinesis](/destinations/kinesis), or [S3](/destinations/s3) destination. diff --git a/src/docs.json b/src/docs.json index ab0120ee..90438cfb 100644 --- a/src/docs.json +++ b/src/docs.json @@ -58,6 +58,7 @@ "pages": [ "destinations/overview", "destinations/webhooks", + "destinations/slack", "destinations/kinesis", "destinations/s3" ] diff --git a/src/notifications/overview.mdx b/src/notifications/overview.mdx index 1323abcb..c69d5bad 100644 --- a/src/notifications/overview.mdx +++ b/src/notifications/overview.mdx @@ -56,7 +56,7 @@ There are two ways to set up notifications: - Go to [Destinations](https://dashboard.withampersand.com/projects/_/settings/destinations/) - Click **New Destination** and configure: - **Name**: A descriptive name (e.g., "production-alerts") - - **Type**: Choose webhook, Kinesis, Amazon S3, or log destination + - **Type**: Choose webhook, [Slack](/destinations/slack), Kinesis, Amazon S3, or log destination - **Configuration**: Provide the endpoint URL or stream details - Click **Create Destination** From b381f69bf283a2f843d1f42a832011aeecb1b940 Mon Sep 17 00:00:00 2001 From: Rajat Pawar <18614743+RajatPawar@users.noreply.github.com> Date: Mon, 3 Aug 2026 16:55:42 -0700 Subject: [PATCH 2/5] Revise Slack destination documentation Updated the Slack destination documentation to clarify use cases and improve readability. --- src/destinations/slack.mdx | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/src/destinations/slack.mdx b/src/destinations/slack.mdx index 255d4568..f1424ef1 100644 --- a/src/destinations/slack.mdx +++ b/src/destinations/slack.mdx @@ -4,7 +4,7 @@ title: Slack destinations For more information on destinations, see the [Destinations](/destinations) page. -A Slack destination delivers messages to a Slack channel using a [Slack incoming webhook](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks). It's a great fit for [Notifications](/notifications) — for example, posting a message to your team's channel whenever a customer connects an integration or a sync runs into an error. +A Slack destination delivers messages to a Slack channel using a [Slack incoming webhook](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks). It's a great fit for [Notifications](/notifications) or quickly testing webhook payloads. For example, posting a message to your team's channel whenever a customer connects an integration or a sync runs into an error may be a good fit for this destination. ## Setting up a Slack destination @@ -12,14 +12,10 @@ A Slack destination delivers messages to a Slack channel using a [Slack incoming 2. In the [Ampersand Dashboard](https://dashboard.withampersand.com/projects/_/destinations), add a new destination of type **Slack** and paste in that URL. (The URL must be a `hooks.slack.com` URL.) -The Slack channel is fixed when you create the incoming webhook — Ampersand posts to that channel and cannot override it. +The Slack channel is fixed when you create the incoming webhook. Ampersand posts to that channel and cannot override it. -## What Ampersand posts to Slack - -Ampersand reshapes each message into Slack's format before sending it. - -### Notifications +## Notifications Notifications are rendered as a short, human-friendly sentence, followed by the raw notification payload for full detail. For example, a `connection.error` notification appears as: @@ -28,8 +24,8 @@ Notifications are rendered as a short, human-friendly sentence, followed by the > {"notificationType":"connection.error","data":{ ... }} > ``` -Route notification events to a Slack destination the same way as any other destination — see the [Notifications overview](/notifications) for setup. +You can route notification events to a Slack destination the same way as any other destination. See the [Notifications overview](/notifications) for setup. -### Read & subscribe data +## Read & subscribe data -Data synced via [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions) is delivered as the JSON payload nested directly into the Slack message text. Because Slack renders message text as markdown, Slack destinations are best suited to notifications and low-volume data; for high-volume data delivery, use a [webhook](/destinations/webhooks), [Kinesis](/destinations/kinesis), or [S3](/destinations/s3) destination. +Data read via [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions) is delivered as the JSON payload nested directly into the Slack message text. From a87b090b9687c9c055929d41cebeb2f0691aeb4b Mon Sep 17 00:00:00 2001 From: RajatPawar <18614743+RajatPawar@users.noreply.github.com> Date: Mon, 3 Aug 2026 17:00:31 -0700 Subject: [PATCH 3/5] docs(destinations): add slack to nav source + Slack size-limit warning (ENG-4113) - Add destinations/slack to the nav in generate-docs.ts (the source for the auto-generated docs.json) so the two stay in sync. - Warn that Slack accepts ~16 KB per message; larger data delivery payloads are rejected by Slack. Co-Authored-By: Claude Opus 4.8 --- src/destinations/slack.mdx | 4 ++++ src/generate-docs.ts | 1 + 2 files changed, 5 insertions(+) diff --git a/src/destinations/slack.mdx b/src/destinations/slack.mdx index f1424ef1..e3077af2 100644 --- a/src/destinations/slack.mdx +++ b/src/destinations/slack.mdx @@ -29,3 +29,7 @@ You can route notification events to a Slack destination the same way as any oth ## Read & subscribe data Data read via [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions) is delivered as the JSON payload nested directly into the Slack message text. + + +Slack accepts roughly **16 KB** per message. Larger payloads are rejected by Slack, so be careful using Slack destinations for data delivery — a single record or batch that exceeds this limit will not be delivered. For anything beyond small payloads, use a [webhook](/destinations/webhooks), [Kinesis](/destinations/kinesis), or [S3](/destinations/s3) destination instead. + diff --git a/src/generate-docs.ts b/src/generate-docs.ts index 8f39d6f9..504f90a5 100644 --- a/src/generate-docs.ts +++ b/src/generate-docs.ts @@ -289,6 +289,7 @@ const baseConfig = { pages: [ "destinations/overview", "destinations/webhooks", + "destinations/slack", "destinations/kinesis", "destinations/s3", ] From 3faa9a783833e0fc871a17f0a07e4997cec24d8d Mon Sep 17 00:00:00 2001 From: RajatPawar <18614743+RajatPawar@users.noreply.github.com> Date: Mon, 3 Aug 2026 17:04:21 -0700 Subject: [PATCH 4/5] docs(destinations): Slack truncates (not rejects) large messages (ENG-4113) Co-Authored-By: Claude Opus 4.8 --- src/destinations/slack.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/destinations/slack.mdx b/src/destinations/slack.mdx index e3077af2..8ff69c13 100644 --- a/src/destinations/slack.mdx +++ b/src/destinations/slack.mdx @@ -31,5 +31,5 @@ You can route notification events to a Slack destination the same way as any oth Data read via [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions) is delivered as the JSON payload nested directly into the Slack message text. -Slack accepts roughly **16 KB** per message. Larger payloads are rejected by Slack, so be careful using Slack destinations for data delivery — a single record or batch that exceeds this limit will not be delivered. For anything beyond small payloads, use a [webhook](/destinations/webhooks), [Kinesis](/destinations/kinesis), or [S3](/destinations/s3) destination instead. +Slack renders roughly **16 KB** per message and **silently truncates** anything larger — the request still succeeds, so oversized content is dropped without an error. Be careful using Slack destinations for data delivery: a large record or batch will be cut off. For anything beyond small payloads, use a [webhook](/destinations/webhooks), [Kinesis](/destinations/kinesis), or [S3](/destinations/s3) destination instead. From 2584ff09cb5ef1cdf3c8f1c120051acbc70199fd Mon Sep 17 00:00:00 2001 From: Rajat Pawar <18614743+RajatPawar@users.noreply.github.com> Date: Mon, 3 Aug 2026 17:07:36 -0700 Subject: [PATCH 5/5] Clarify Slack message size limit to 16-20 KB Updated the message size limit information for Slack destinations. --- src/destinations/slack.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/destinations/slack.mdx b/src/destinations/slack.mdx index 8ff69c13..b09bee1d 100644 --- a/src/destinations/slack.mdx +++ b/src/destinations/slack.mdx @@ -31,5 +31,5 @@ You can route notification events to a Slack destination the same way as any oth Data read via [Read Actions](/read-actions) or [Subscribe Actions](/subscribe-actions) is delivered as the JSON payload nested directly into the Slack message text. -Slack renders roughly **16 KB** per message and **silently truncates** anything larger — the request still succeeds, so oversized content is dropped without an error. Be careful using Slack destinations for data delivery: a large record or batch will be cut off. For anything beyond small payloads, use a [webhook](/destinations/webhooks), [Kinesis](/destinations/kinesis), or [S3](/destinations/s3) destination instead. +Slack renders roughly **16-20 KB** per message and **silently truncates** anything larger. The request still succeeds, so oversized content is dropped without an error. Be careful using Slack destinations for data delivery: a large record or batch may be cut off. For anything beyond small payloads, use a [webhook](/destinations/webhooks), [Kinesis](/destinations/kinesis), or [S3](/destinations/s3) destination instead.