Slack Events API

Slack’s Events API delivers JSON over HTTPS and requires a URL verification handshake before events flow. HookNexus can receive both the challenge and subsequent event deliveries so you can inspect payloads and headers in one place.

How Slack talks to your endpoint

1. URL verification — Slack sends url_verification with a challenge string; your endpoint must echo challenge in JSON.
2. Events — After verification, Slack POSTs event envelopes (e.g. event_callback) signed with X-Slack-Signature.

Note

HookNexus captures whatever your URL returns. For a persistent Slack integration, your production app must respond to url_verification automatically. Use HookNexus to debug payloads and signatures; for automated challenge handling you may need your own small service or Slack’s Socket Mode in development.

Setup in Slack

1. Create or open a Slack app

   Go to api.slack.com/apps, select your app (or create one).

2. Enable Event Subscriptions

   In the app settings, open Event Subscriptions and turn Enable Events on.

3. Set the Request URL

   Enter your HookNexus webhook URL:

   https://api.hooknexus.com/h/YOUR_ENDPOINT_ID

4. Complete URL verification

   Slack sends a url_verification event. Your endpoint must respond with JSON {"challenge":"<value>"}.

   If verification stays pending, use a temporary handler that returns the challenge, or verify manually by inspecting the captured request in HookNexus and understanding what Slack expects—then switch to an app URL that responds correctly.

5. Subscribe to bot/user events

   Under Subscribe to bot events, add events such as message.channels, app_mention, or reaction_added (depending on scopes).

6. Reinstall the app if scopes changed

   After changing scopes, reinstall the app to your workspace from Install App.

Signature verification

Each request includes:

Header	Purpose
X-Slack-Signature	v0=<hex hmac>
X-Slack-Request-Timestamp	Unix seconds; used in the signed base string

The signed payload format is: v0:{timestamp}:{raw_body}

Use HookNexus Verify Signature with provider Slack and your app’s Signing Secret from Basic Information → App Credentials.

curl -X POST https://api.hooknexus.com/api/verify-signature \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "slack",
    "payload": "<raw body>",
    "signature": "v0=...",
    "secret": "your_signing_secret",
    "timestamp": "<X-Slack-Request-Timestamp>"
  }'

The timestamp field must match X-Slack-Request-Timestamp—it is part of the signed base string v0:{timestamp}:{body}.

Tip

Copy the Signing Secret from Basic Information → App Credentials in your Slack app settings.

Common events

Event / pattern	Use case
message	Channel messages (with appropriate scopes)
app_mention	Bot responds when @mentioned
reaction_added	Emoji reactions on messages

Event names appear inside the JSON envelope (event.type).

Troubleshooting

Symptom	What to check
Request URL never verifies	Response must be 200 with correct JSON challenge; Slack expects a response within a few seconds.
No events after verify	Confirm events are subscribed and bot is in the channel (for channel messages).
Invalid signature	Use Signing Secret from the same app; raw body must match Slack’s bytes.
Duplicate events	Slack retries on timeouts; use event_id for deduplication in your app.

Development

Consider Socket Mode for local dev without a public URL; use HookNexus when you want HTTP capture of the same event shapes.

Security

Reject requests with timestamps too far from current time to mitigate replay attacks when you implement verification yourself.