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

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

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

Square чекає на 2xx і вважає невдачею відповідь, яка не вклалася в 10 секунд. Після цього він повторює з експоненційною затримкою протягом доби, додаючи заголовки square-retry-number і square-retry-reason. Якщо підписка за три тижні не поверне жодного 2xx, Square попереджає листом і вимикає її. (Square: Webhooks overview)

Коли попереду стоїть Railhook:

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

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

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

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

Створіть джерело без секрету. Square покаже Signature Key лише після того, як підписка з’явиться:

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":"Square","providerType":"SQUARE","verificationMode":"NONE"}'

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

Створіть підписку в Square Developer Console. Відкрийте свій застосунок, перейдіть у Webhooks → Subscriptions, угорі сторінки виберіть Sandbox або Production (у них окремі підписки) і натисніть Add subscription. Вставте ingressUrl точно так, як його показує джерело, у поле адреси сповіщень і виберіть потрібні типи подій. (Square: Subscribe to event notifications)
Скопіюйте Signature Key. Відкрийте деталі ендпоінта підписки й натисніть Show біля Signature Key. Саме цим ключем Square підписує сповіщення.

Передайте ключ Railhook і ввімкніть перевірку:

curl -X PUT "$RAILHOOK_URL/api/v1/projects/$PROJECT_ID/incoming-sources/$SOURCE_ID" \
  -H "X-API-Key: $RAILHOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Square","verificationMode":"PROVIDER","hmacSecret":"'"$SQUARE_SIGNATURE_KEY"'"}'

Поле name під час оновлення обов’язкове; усе інше, що ви не вказали, лишається як було.

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

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/square","authType":"BEARER","authConfig":"{\"token\":\"...\"}","enabled":true}'

Надішліть тестову подію зі сторінки підписки в Developer Console. Вона з’явиться в розділі «Вхідні → Отримані», з одним пересиланням на кожне призначення.

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

x-square-hmacsha256-signature у Square є HMAC-SHA256 у Base64 від адреси сповіщення, за якою одразу йде необроблене тіло, без жодного роздільника, з ключем Signature Key. Railhook обчислює те саме й порівнює за сталий час. Запит, який не збігся, отримує 401 і не зберігається.

Це звичайна причина невдалої перевірки Square. http там, де в Square https, зайва скісна риска в кінці чи інший хост змінюють хеш, і всі справжні сповіщення перестають проходити перевірку. Railhook складає адресу зі своєї налаштованої публічної адреси, а не з вхідного запиту, тож зворотний проксі її не зіпсує. На власному сервері це APP_BASE_URL, який інсталятор бере з --domain, або TUNNEL_INGRESS_BASE_URL, якщо вебхуки приходять на інший хост. Вставляйте в Square саме ту ingress-адресу, яку показує джерело, символ у символ. Див. Конфігурація.

Схема Square не має мітки часу, тож незмінне тіло завжди дає той самий підпис. Повторну спробу самого Square від відтворення відрізняє event_id сповіщення, який Square описує як значення для ідемпотентності: Railhook його зберігає, і на друге сповіщення з уже відомим event_id відповідає збереженою подією замість повторного пересилання.

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

Тіло точно таким, яким його надіслав Square, байт у байт, і власні заголовки Square, зокрема square-environment, з якого видно, прийшло сповіщення із Sandbox чи з Production. Заголовок x-square-hmacsha256-signature не пересилається: ваш сервіс автентифікує Railhook обліковими даними призначення, і Signature Key йому ні до чого. Див. Призначення.

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

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

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

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

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