Як надійно отримувати події Slack

Slack надсилає події Events API на джерело Railhook. Джерело перевіряє підпис, зберігає кожну подію такою, якою вона надійшла, і пересилає її у ваш сервіс із повторними спробами. Railhook відповідає Slack одразу, тож через повільний обробник Slack більше не вимикає ваші підписки на події.

Чому подіям Slack потрібен буфер

Slack просить застосунок відповідати на кожну подію 2xx протягом трьох секунд. Невдалу подію він повторює тричі (майже одразу, через 1 хвилину й через 5 хвилин) і позначає кожну повторну спробу заголовком x-slack-retry-num. Якщо за 60 хвилин застосунок не відповів щонайменше на 5% подій, Slack тимчасово вимикає його підписки на події й надсилає листа власникові застосунку. (Slack: The Events API)

Повторних спроб протягом приблизно п’яти хвилин не вистачить, щоб оговтатися після невдалого деплою. Коли попереду стоїть Railhook:

Railhook відповідає Slack, щойно збереже подію, задовго до спливу трьох секунд.
Ваш сервіс отримує до 5 спроб на кожне пересилання з інтервалами від 1 хвилини до 1 години, а те, що так і не вдалося доставити, потрапляє в «Недоставлені пересилання».
Повторна спроба від Slack має той самий event_id. Railhook його розпізнає, відповідає збереженою копією і вдруге подію не пересилає.

Підключення Slack

Знадобляться проєкт Railhook і API-ключ. Ті самі кроки є в панелі керування, у розділі «Вхідні».

export RAILHOOK_URL=https://railhook.io   # or your own instance
export RAILHOOK_API_KEY=...
export PROJECT_ID=...

Скопіюйте секрет підпису. У налаштуваннях застосунку на api.slack.com відкрийте Basic Information і скопіюйте Signing Secret у розділі App Credentials.

Створіть джерело з цим секретом:

curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/incoming-sources" \
  -H "X-API-Key: $RAILHOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Slack","providerType":"SLACK","verificationMode":"PROVIDER","hmacSecret":"'"$SLACK_SIGNING_SECRET"'"}'

Збережіть id і ingressUrl із відповіді.

Додайте призначення, URL вашого сервісу:

curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/incoming-sources/$SOURCE_ID/destinations" \
  -H "X-API-Key: $RAILHOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://api.example.com/webhooks/slack","authType":"BEARER","authConfig":"{\"token\":\"...\"}","enabled":true}'

Увімкніть події в Slack. Відкрийте Event Subscriptions, увімкніть їх і вставте ingressUrl у поле Request URL. Slack надішле запит-підтвердження url_verification; Railhook перевірить його підпис і поверне значення challenge, тож Slack прийме URL. Підтвердження не є подією: нічого не зберігається й не пересилається.
Підпишіться на bot events, збережіть зміни й згенеруйте подію, наприклад напишіть повідомлення в каналі, де є застосунок. Вона з’явиться в розділі «Вхідні» → «Отримані» з одним пересиланням на кожне призначення.

Як перевіряється підпис

Railhook читає X-Slack-Signature і X-Slack-Request-Timestamp, обчислює v0=, а за ним HMAC-SHA256 від v0:<timestamp>:<raw body> у hex із секретом підпису, і порівнює одне з одним. Мітка часу має відрізнятися від часу на годиннику Railhook не більш ніж на 300 секунд. На запит, що не збігається, Railhook відповідає 401 і не зберігає його. Цю саму схему Slack описує в Verifying requests from Slack.

Що отримує ваш сервіс

Тіло точно таке, яким його надіслав Slack, байт у байт, з оригінальним Content-Type. X-Slack-Signature не пересилається: ваш сервіс автентифікує Railhook за обліковими даними призначення, тож секрет підпису йому не потрібен. Кожен запит містить Idempotency-Key, однаковий для всіх спроб. Див. Призначення.

Локальна розробка з CLI

Встановіть CLI й увійдіть, як описано в CLI, а потім відкрийте тунель до порту вашого застосунку:
Terminal window
```
railhook listen 3000
```
Додайте джерелу друге призначення: публічну адресу, яку вивела команда, з вашим маршрутом у кінці, наприклад https://<host>/tunnel/<slug>/webhooks/slack. Запит потрапить на http://localhost:3000/webhooks/slack.
Напишіть повідомлення в тестовому робочому просторі Slack, і перевірена подія надійде у ваш локальний застосунок. Request URL у Slack так і лишається ingress-адресою, тож після перезапуску тунелю підтверджувати його знову не треба. Коли закриєте тунель, вимкніть це призначення.

Відтворення після збою

Кожна відтворена подія піде на кожне призначення джерела як нове пересилання:

curl -X POST "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/incoming-events/bulk-replay" \
  -H "X-API-Key: $RAILHOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sourceId":"'"$SOURCE_ID"'","from":"2026-09-18T10:00:00Z","to":"2026-09-18T14:00:00Z","verified":true}'

Відтворити можна все, що ще зберігається: 7 днів у Railhook Cloud і скільки налаштуєте на власному сервері. Обробник має залишатися ідемпотентним за event_id, бо відтворення може надіслати події, які ваш сервіс уже обробив. Див. Відтворення.