Consuming Slack Webhooks: Event Subscriptions, Verification & Retries

Slack’s Events API and Interactivity endpoints deliver real-time messages, mentions, reactions, and button interactions to your bot backend over HTTP POST.

Slack has strict timeout constraints: if your endpoint does not respond with HTTP 200 OK within 3 seconds, Slack considers the delivery failed and immediately begins retrying with headers X-Slack-Retry-Num and X-Slack-Retry-Reason.

How Slack Webhooks work

1. URL Verification Handshake

When you configure an Event Subscription URL in the Slack App settings, Slack sends a one-time challenge:

{
  "type": "url_verification",
  "token": "Jhj54699...deprecated",
  "challenge": "3eZbrw1aW..."
}

Your endpoint must immediately respond with 200 OK and plaintext challenge string.

2. Event Callbacks

Normal events arrive wrapped in an event_callback envelope:

• event: The event body (type, user, text, channel, ts).
• event_id: Unique event identifier (prefixed Ev...).
• event_time: Unix epoch timestamp.

Verifying Slack signatures (X-Slack-Signature)

Slack signs every request with your App’s Signing Secret using version v0:

• X-Slack-Request-Timestamp: Unix timestamp.
• X-Slack-Signature: v0= followed by the hex-encoded HMAC-SHA256 hash.

Verification Algorithm:

1. Ensure the timestamp is within 5 minutes of current time: abs(now - timestamp) < 300.
2. Construct signature basestring: "v0:" + timestamp + ":" + rawBody.
3. Compute hmac_sha256(signing_secret, basestring).
4. Prefix with "v0=" and compare with X-Slack-Signature using constant-time comparison (crypto.timingSafeEqual).

The 3-second timeout rule

Because Slack will retry aggressively after 3 seconds, never perform slow AI generation, database writes, or third-party API calls inside the request handler. Return 200 OK instantly and push the event to a background job or queue for asynchronous processing.

Inspecting Slack Events with HookWatch

• Inspect the exact event_callback payloads and headers sent by Slack.
• Check whether an event was a retry (X-Slack-Retry-Reason: http_timeout).
• Replay missed bot mentions after fixing handler bugs without asking users to re-type messages.