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..b09bee1d --- /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) 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 + +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. + + +## 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":{ ... }} +> ``` + +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 + +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-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. + 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/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", ] 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**