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.
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
v0:{timestamp}:{raw body} The literal v0, the X-Slack-Request-Timestamp value and the request body as sent, joined with colons.
GET or POST: echo the challenge Answer 200 with the challenge value as text/plain.
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 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_verificationPOST with HTTP 200 and thechallengevalue. 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 runstarts 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
3 seconds respond with an HTTP 2xx; Slack's docs offer no way to extend it Retries 3 attempts nearly immediately, after 1 minute and after 5 minutes, or hourly for 24 hours with Delayed Events After repeated failures subscriptions disabled over 95% of attempts failing in 60 minutes, unless the app gets under 1,000 events an hour Ordering no general promise app_uninstalled and tokens_revoked are documented as possibly out of sequence Known failure modes
From Hookdeck's Slack guide →-
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 → -
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
Handle duplicates →event_id, and usex-slack-retry-reasonto see why a retry was sent. -
A handler switching on message.channels never matches
Choosing events →message.channelsis the name you subscribe to, while the delivery'sevent.typeismessage. Switch onevent.typeand readevent.channel_typeto tell public channels, private channels and DMs apart. -
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
Rate limits →app_rate_limitedevery minute. That payload has noeventobject, so code readingevent.typethrows on it.
Slack webhook best practices
- Verify every signature.
Check it on the raw body, and reject timestamps more than five minutes from your clock. The
tokenfield 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_idof 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 outertypefirst 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 | 13 | 13 |
channel | 11 | 11 |
message | 11 | 11 |
user | 9 | 9 |
file | 7 | 7 |
workspace | 7 | 7 |
private_channel | 6 | 6 |
reaction | 6 | 2 |
shared_channel | 5 | 5 |
user_group | 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.