How to Create a Slack Bot with a Secure Events API Handler

Prepare the Slack app and one narrow event contract

Start with a controlled workspace and an incident fixture that contains no customer or employee secrets. Decide exactly which event wakes the bot and which channel data it may read.

• A Slack workspace with installation authority: Use a development workspace or obtain administrator approval. Record who owns the app, who can rotate credentials, and whether the app will remain internal or require a distribution review.
• A public HTTPS Events API endpoint: The endpoint must preserve raw request bytes, read Slack signature headers, write a durable event claim quickly, and return HTTP 200 before doing incident lookup or message generation.
• A durable event store and worker: Use a unique constraint on `event_id`, keep a pending state before acknowledgement, and let a worker recover pending events if dispatch fails after the response.
• A least-privilege incident lookup: Define which incident fields may appear in a channel, who can request them, and how private channels or sensitive incidents are rejected. A mention does not automatically authorize every record.

Credentials and access

Slack platform constraints

• Slack signs HTTP requests with the app signing secret. Compute HMAC-SHA256 from `v0:{timestamp}:{rawBody}` before a framework parses or rewrites the body, then compare the complete `v0=` signature using a timing-safe function.
• Reject requests whose `X-Slack-Request-Timestamp` differs from local time by more than five minutes. Signature validity alone does not stop capture-and-replay inside an unlimited time window.
• Slack expects a successful Events API acknowledgement within three seconds and retries failed deliveries. Its outer event envelope includes a globally unique `event_id`, which is the correct idempotency key for one delivery effect.
• For a bot that listens only when mentioned and posts a reply, start with `app_mentions:read` and `chat:write`. Workspace administrators may still need to approve installation, and distribution or Marketplace review adds policy requirements.
• Slack plan features, rate limits, admin settings, retention, Marketplace rules, and API terms can change. Re-check official documentation and the target workspace before release.

Official references: Verifying requests from Slack, Slack Events API, Using HTTP Request URLs, url_verification event, app_mention event, chat.postMessage method

Choose the inbound Slack delivery model

The Events API can reach an HTTPS request URL or use Socket Mode. The event contract is similar, but the trust boundary and operations differ.

Recommended:Use HTTPS for a hosted production bot because it aligns with Playcode deployment and keeps the sample reproducible. Persist `event_id` before acknowledging and process from storage. Choose Socket Mode only when the private-network constraint justifies a continuously connected worker.

Create a Slack incident-triage bot

Create and install a least-privilege Slack app, implement raw-body request verification and durable event identity, run fixtures, deploy HTTPS, and finish with a controlled workspace smoke test.

const base = Buffer.concat([
  Buffer.from(`v0:${timestamp}:`, 'utf8'),
  rawBody,
])
const expected = `v0=${createHmac('sha256', signingSecret)
  .update(base)
  .digest('hex')}`
if (!sameSignature(supplied, expected)) return unauthorized()

What the result can look like

Test authentication, retries, and the real provider boundary

Local fixtures should prove deterministic request behavior. The final published smoke test is separate because it needs your Slack app, workspace, credentials, and channel.

Common Slack bot failures

Use the request headers, bounded event metadata, provider settings, and durable state to locate the failed boundary before changing code.

Operate the bot as a small event system

Deploy

Deploy the HTTPS receiver, durable event table, worker, and outbound Slack adapter as separate responsibilities. Keep signing and OAuth secrets server-side and validate the Request URL before enabling the event subscription.

Record the installed workspace, granted scopes, subscribed events, app owner, recovery owner, and last manual smoke date. Treat scope changes as a new security review and reinstall boundary.

Monitor

Track acknowledgement latency, signature and replay rejections, event inserts, duplicate IDs, pending age, worker attempts, Slack API errors, rate limits, and redacted end-to-end smoke results.

Use event ID, app ID, team ID, channel classification, timestamps, and bounded error codes for diagnosis. Do not log signing secrets, OAuth tokens, authorization headers, or full private messages by default.

Recover

If the receiver acknowledged but dispatch failed, scan pending durable records and resume by event ID. Do not rely on Slack to redeliver an event that already received HTTP 200.

If a credential is exposed, rotate or reinstall the app, update secrets, confirm old access is revoked, and rerun URL verification plus the controlled mention smoke test.

Keep workspace access and incident data bounded

The inbound signature proves which Slack app sent the request. It does not authorize every channel member to read every incident or make every action.

• Verify the fresh timestamp and HMAC signature over raw bytes before JSON parsing, storage, lookup, or outbound calls.
• Keep the signing secret and bot OAuth token separate, server-side, redacted, and rotatable. Never put either in generated UI or downloadable examples.
• Start with `app_mentions:read` and `chat:write`; add history, user, file, or admin scopes only for a reviewed feature that cannot work without them.
• Authorize the requester, workspace, channel, and incident record before revealing operational data or executing an action.
• Use durable `event_id` idempotency and a recoverable outbox or equivalent for outbound effects. Redact channel messages from routine logs.

Slack bot questions