Як надійно отримувати вебхуки GitLab

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

Чому вебхукам GitLab потрібен буфер

GitLab вимикає вебхук, який раз у раз падає. Після чотирьох невдач поспіль він вимикає його на одну хвилину, а якщо невдачі тривають, то до 24 годин. Після 40 невдач поспіль вебхук вимикається назавжди і сам не ввімкнеться. Вебхук, що завершився тайм-аутом, також може прийти повторно як дублікат. (GitLab: Webhooks)

Кілька невдалих деплоїв можуть непомітно вимкнути вашу інтеграцію. Коли попереду стоїть Railhook:

Railhook відповідає на запити GitLab, щойно їх збереже, тож через ваш сервіс вони не завершуються тайм-аутом і не падають.
Ваш сервіс отримує до 5 спроб на кожне пересилання з інтервалами від 1 хвилини до 1 години, а те, що так і не вдалося доставити, потрапляє в «Недоставлені пересилання».
На дублікат із тим самим заголовком webhook-id чи Idempotency-Key Railhook відповідає збереженою копією і вдруге його не пересилає.

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

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

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

Виберіть секретний токен. У GitLab ви задаєте його самі:
Terminal window
```
export GITLAB_WEBHOOK_TOKEN=$(openssl rand -hex 32)
```

Створіть джерело, указавши цей токен як секрет:

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":"GitLab","providerType":"GITLAB","verificationMode":"PROVIDER","hmacSecret":"'"$GITLAB_WEBHOOK_TOKEN"'"}'

Збережіть 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/gitlab","authType":"BEARER","authConfig":"{\"token\":\"...\"}","enabled":true}'

Зареєструйте вебхук у GitLab. У проєкті чи групі відкрийте Settings → Webhooks і додайте новий вебхук. Вставте ingressUrl у поле URL, той самий токен у Secret token і позначте потрібні тригери.
Надішліть тестовий вебхук кнопкою Test. Він з’явиться в розділі «Вхідні» → «Отримані» з одним пересиланням на кожне призначення.

Як перевіряється токен

GitLab не підписує тіло, а надсилає секретний токен у заголовку X-Gitlab-Token. Railhook перевіряє, чи заголовок дорівнює секрету джерела, і якщо ні, відповідає 401 і нічого не зберігає. Токен не є підписом, тож тримайте ingress-адресу в таємниці й відкривайте її лише через HTTPS.

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

Тіло точно таке, яким його надіслав GitLab, байт у байт. Railhook передає далі заголовки подій GitLab (X-Gitlab-Event, X-Gitlab-Event-UUID і X-Gitlab-Instance), тож ваш сервіс відрізнить push від merge request. X-Gitlab-Token ніколи не пересилається: натомість ваш сервіс автентифікує Railhook за обліковими даними призначення. Див. Призначення.

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

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

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

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

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 і скільки налаштуєте на власному сервері. Зробіть обробник ідемпотентним щодо предмета вебхука, наприклад коміту чи merge request у тілі, бо відтворення може надіслати вебхуки, які ваш сервіс уже обробив. Див. Відтворення.