Using legacy custom integrations is an outdated way for teams to integrate with Slack. Legacy custom integrations lack newer features and will be deprecated and possibly removed in the future. We do not recommend their use.

We recommend using their replacement: Slack apps. Slack apps can be built just for your own workspace or distributed through the App Directory, and they can use the latest and greatest APIs and UI features.

Legacy custom integrations outgoing webhooks

Outgoing Webhooks are a legacy method of sending notifications to an app about two specific activities:

  1. A message was posted in a particular public Slack channel.
  2. A message was posted in any public Slack channel containing specific trigger words.

Because we strongly recommend you do not use legacy custom integrations anymore, you should instead use the Events API with Slack apps. Our guide to the Events API will walk you through the process of enabling this functionality in a Slack app.

If you were using outgoing webhooks to provide a bot-like behavior with your legacy integration, you might be interested in reading our Handling user interaction in your Slack apps guide.


Migrating from legacy integrations

If you previously created any outgoing Webhooks using legacy integrations, you should switch to a Slack app and replicate the functionality using the Events API.

The Events API can be used to replace this by subscribing to the message.channels event type. This will push a data payload to an app every time a message is posted to a public channel.

When an app receives that data payload, it'll be able to see both the source channel and the text of the posted message. Using channel will help replicate the first outgoing Webhook feature, and looking for the trigger words in the text string will replicate the second.

Even better, while Outgoing Webhooks only worked for public channels, the Events API can be used with private channels, direct message conversations, or multi-party direct message conversations. There are also dozens of other event types available for subscription, and for your app to react to. Read the Events API overview for a better idea of all the things you can use it for.


Legacy information

Though we recommend that all legacy custom integrations should migrate to Slack apps, we also understand that some will still need to maintain older integrations. This section contains any information about using outgoing Webhooks that is specific to the legacy implementation.

Legacy management

If you need to configure your legacy integrations, you can access the Integrations management pages here.

Channel and/or Trigger

If an outgoing webhook is not configured to respond when a message is posted in a specific channel, then the trigger word(s) are required -- otherwise, the trigger word(s) are optional.

If both are specified, then the message must match both conditions.

POST Data

When a chat message is received that matches the conditions, a POST will be sent to all of the URLs defined like so:

token=XXXXXXXXXXXXXXXXXX
team_id=T0001
team_domain=example
channel_id=C2147483705
channel_name=test
thread_ts=1504640714.003543
timestamp=1504640775.000005
user_id=U2147483697
user_name=Steve
text=googlebot: What is the air-speed velocity of an unladen swallow?
trigger_word=googlebot:

Please note that the content of message attachments will not be included in the outgoing POST data.

Responding

If the handler wishes to post a response back into the channel, the following JSON should be returned as the body of the response:

{
    "text": "African or European?"
}

Empty bodies or bodies with an empty text property will be ignored. Non-200 responses will be retried a reasonable number of times.

Responses will be posted using the bot name and icon configured in the integration. However, if you would like to change the name on a per-response basis, include the username parameter in your response.

Rate Limits

Outgoing webhooks sent by a legacy integration are limited to no more than one message per second, with bursts allowed over short periods to accommodate periods of high activity.

If your legacy integration goes over this limit, outgoing webhooks for subsequent messages will not be sent until the rate has gone below the one webhook per second limit.

This limit exists to prevent us sending your servers more events than you or we can handle. The Events API, which can be used with Slack apps as above has different rate limits which may be more suitable for your use case.