Verifying Slack request signatures: X-Slack-Signature, the 5-minute replay window and the 3-second rule

What it is

Slack's request-verification guide has a receiver read the raw body with something like get_data() "in order to get the raw request payload, without performing JSON deserialization", then build a basestring by concatenating "the version number, the timestamp, and the request body together, using a colon (:) as a delimiter", giving a string such as v0:1531420618:token=.... The HMAC-SHA256 digest of that string, hex-encoded and prefixed v0=, is compared against X-Slack-Signature; Slack's docs recommend using "an hmac compare function instead of directly comparing the signatures for equality." The X-Slack-Request-Timestamp header guards against replay: Slack's own example "verif[ies] that the timestamp does not differ from local time by more than five minutes." Slack's guide includes a worked example (secret 8f742231b10e8888abcd99yyyzzz85a5, timestamp 1531420618, expected v0=a2114d57...9c69b503) that makes a good unit test. Separately, for slash commands, Slack's implementation guide comments "Acknowledge the command within 3 seconds", and otherwise "an operation_timeout error will be displayed to the user"; interaction payloads must likewise be acknowledged "within 3 seconds of receiving the payload", and Events API deliveries within three seconds or Slack retries them.

Why it matters

The signature proves the request came from Slack and was not altered; the timestamp check stops a captured, valid request from being replayed later. The 3-second rule is unrelated to signing but just as strict: Slack's servers time out an unacknowledged slash command or interaction, so any real work (calling an LLM, hitting a database, posting to another API) must happen after an immediate acknowledgement, not before it.

How to apply

• Read the raw body before any framework helper deserialises it into a dict.
• Reject if abs(now - X-Slack-Request-Timestamp) > 300 seconds.
• Build v0:{timestamp}:{raw_body}, HMAC-SHA256 it with the signing secret, prefix v0=, and compare with a constant-time function against X-Slack-Signature.
• For slash commands and interactivity, return an HTTP 200 (an empty body or minimal acknowledgement) within 3 seconds, then do the real work asynchronously and post the result back via response_url or a Web API call.

import hmac, hashlib, time

def verify_slack(signing_secret: str, timestamp: str, raw_body: bytes, sig_header: str) -> bool:
    if not timestamp.isdecimal() or abs(time.time() - int(timestamp)) > 300:
        return False
    base = b"v0:" + timestamp.encode() + b":" + raw_body   # exact bytes Slack signed
    digest = hmac.new(signing_secret.encode(), base, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"v0={digest}".encode(), sig_header.encode())

Pitfalls

Doing the slow work synchronously inside the request handler that must answer within 3 seconds, which produces an intermittent, load-dependent failure that is easy to miss in light testing. Verifying the signature after a JSON-parsing middleware has already consumed and reformatted the body. Skipping the timestamp check because the signature alone "looks like enough".