Slack webhooks

Slack webhooks, in the Events API sense, are signed HTTP POSTs Slack sends to your app's Request URL when something happens in a workspace, and they run the opposite way to incoming webhooks, which post messages into a channel.

91 events covered

These pages cover the Events API, which Slack uses to send events to your app. To post messages into a channel, see incoming webhook limits or how to send external webhooks to Slack.

How Slack webhooks work

The Events API tells your app about messages, reactions, channel changes and app installs without polling or a long-lived connection. Your app has one Request URL, which receives every event it subscribes to from every workspace that installs it, so any routing happens on your side. Each event is its own JSON POST. Socket Mode delivers the same events over a WebSocket instead, and Slack recommends it for local development and HTTP for production.

The outer type is event_callback for an event, and event.type says what happened, such as reaction_added. Two types have no inner event, so read the outer type for them: url_verification and app_rate_limited. You subscribe to names like message.channels, but those deliveries carry event.type: message and event.channel_type says where it was posted. Message changes and deletions arrive as message with an event.subtype. Payloads have no version field, and Slack says to expect fields you haven't seen before.

Key facts

Signature header
X-Slack-Signature

Format: v0=<hex>

Scheme
HMAC-SHA256
Signed material
v0:{timestamp}:{raw body}

The literal v0, the X-Slack-Request-Timestamp value and the request body as sent, joined with colons.

How events are identified
event.type field in the body
Body format
JSON

Content type: application/json.

Send timestamp
X-Slack-Request-Timestamp

Reject deliveries older than 5 minutes.

URL handshake
GET or POST: echo the challenge

Answer 200 with the challenge value as text/plain.

Envelope
token, team_id, api_app_id, event, type, event_context, event_id, event_time, authorizations, is_ext_shared_channel, context_team_id, context_enterprise_id
Agent skill
npx skills add hookdeck/webhook-skills --skill slack-webhooks

Verify Slack webhooks →

Setting up Slack webhooks

  • In your app's settings at api.slack.com/apps, open Event Subscriptions, turn it on and enter your Request URL. Slack only saves the URL once your endpoint answers a url_verification POST with HTTP 200 and the challenge value. Then choose bot or workspace events.
  • Test locally with Socket Mode, which needs no public URL, or through a tunnel. The Slack CLI's slack run starts a local server.
  • Slack's docs describe no way to resend an event. Log what you receive, and turn on Delayed Events to extend retries.
  • To post messages to a channel instead, open Incoming Webhooks in the same settings, turn it on and add a webhook to your workspace.

Delivery behaviour

  1. An outage disables your event subscriptions

    If over 95% of delivery attempts fail within 60 minutes, Slack temporarily disables your app's event subscriptions and emails its owner. Delivery stays off until you re-enable it in your app's settings, unless the app gets fewer than 1,000 events an hour.

    Retries and disabled subscriptions →
  2. Slow handlers get duplicate events

    Slack counts a response after 3 seconds as a failure and retries, even if your handler went on to finish the work. Deduplicate on event_id, and use x-slack-retry-reason to see why a retry was sent.

    Handle duplicates →
  3. A handler switching on message.channels never matches

    message.channels is the name you subscribe to, while the delivery's event.type is message. Switch on event.type and read event.channel_type to tell public channels, private channels and DMs apart.

    Choosing events →
  4. Busy workspaces hit the 30,000 event cap

    Event deliveries max out at 30,000 per workspace per app per 60 minutes, and above that Slack sends app_rate_limited every minute. That payload has no event object, so code reading event.type throws on it.

    Rate limits →

Slack webhook best practices

  • Verify every signature. Check it on the raw body, and reject timestamps more than five minutes from your clock. The token field is deprecated, so don't rely on it.
  • Respond within 3 seconds. Return a 200 and move the work to a queue, because a slow response counts as a failure and is retried.
  • Deduplicate on event_id. Retries repeat a delivery. Record the event_id of each event you process and skip the ones you've seen.
  • Watch for disabled subscriptions. Failing over 95% of attempts in an hour disables your subscriptions until you re-enable them, so make sure someone reads the email.
  • Route on the right field. Switch on event.type, not the subscription name, and check the outer type first for the two types with no inner event.
  • Alert on app_rate_limited. Above 30,000 events per workspace per app per hour, Slack sends this every minute you're limited.

Common Slack webhook events

Messages and mentions

app_mention Message in a conversation mentions your bot user
message.channels Subscription for public channel messages; `event.type` is `message`
message.im Subscription for direct messages; `event.type` is `message`

Reactions and members

reaction_added User adds an emoji reaction to an item
member_joined_channel User joins a channel, private channel or group DM
team_join New member joins the workspace

App lifecycle

app_home_opened User opens a tab in your App Home
app_uninstalled Your app is fully removed from a workspace
tokens_revoked Your app's API tokens are revoked

Events by resource

Resource Events Payloads
app

app_home_opened · _context_changed · _deleted · _installed +9

13 13
channel

member_joined_channel · _archive · _created · _deleted +7

11 11
message

app_mention · · link_shared · _metadata_deleted +7

11 11
user

team_join · dnd_updated_user · dnd_updated · _change +5

9 9
file

file_change · _comment_deleted · _created · _deleted +3

7 7
workspace

email_domain_changed · emoji_changed · grid_migration_finished · grid_migration_started +3

7 7
private_channel

group_close · group_deleted · group_history_changed · group_left +2

6 6
reaction

reaction_added · _removed · pin_added · pin_removed +2

6 2
shared_channel

shared_channel_invite_accepted · _invite_approved · _invite_declined · _invite_received +1

5 5
user_group

subteam_created · subteam_members_changed · subteam_self_added · subteam_self_removed +1

5 5

3 more resources, including Other Slack events. All 91 events →

In this hub

Webhook events → Every covered Slack event, with payloads where the registry has them.
MCP events → How an agent subscribes to Slack events as MCP events.
Verify signatures → Signature facts, verification code and common failures.
Production guide → Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
Agent skill → Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill slack-webhooks

Keep an outage from disabling your Slack event subscriptions.

Hookdeck Event Gateway answers Slack's URL verification, accepts every delivery within Slack's 3 seconds, verifies the signature, queues events and retries to your service on your schedule.

Not affiliated with Slack. Facts are compiled from public sources and linked inline.