Перехоплені запити
Коли провайдер каже, що надіслав вебхук, а до ваших ендпоінтів нічого не дійшло, перехоплені запити показують, що насправді надійшло до вашого джерела: кожен заголовок, сире тіло, звідки прийшов запит і що ми відповіли, — включно із запитами, які ми відхилили і які більше ніде не залишають слідів.
Увімкніть запис
Запис вмикається для кожного джерела окремо й за замовчуванням вимкнений, бо перехоплений запит містить сире тіло справжнього вебхука, а для платіжного провайдера це справжні дані клієнтів. Увімкніть його для того джерела, яке налагоджуєте, подивіться, що надходить, і знову вимкніть.
- У консолі: на сторінці Captured requests угорі є перемикач для кожного джерела.
- Через API:
PATCH /v1/sources/{id}з{"capture_enabled": true}.
Відтоді кожен запит на URL прийому цього джерела записується, прийнятий він чи ні.
Що містить перехоплений запит
| Поле | Що це |
|---|---|
| Метод, шлях, query | Рядок запиту в отриманому вигляді. |
| Заголовки | Сирі, у порядку надходження, з дублікатами: якщо провайдер надсилає два заголовки Stripe-Signature, видно обидва. Заголовки з обліковими даними, як-от Authorization і Cookie, приховуються; заголовки підпису зберігаються, бо саме їх ви перевіряєте. |
| Тіло | Перші 64 KiB, точно так, як отримано. Довше тіло позначається як обрізане, а за обрізаним тілом підпис повторно не перевірити. |
| Від кого | IP-адреса відправника. |
| Результат | accepted або причина, з якої ми його відхилили (нижче). |
| Що отримав відправник | Статус, яким ми відповіли, — він збігається з тим, що показує дашборд провайдера. |
| Подія | Для прийнятого запиту — подія, якою він став. |
Повтори обʼєднуються: якщо знову надходять той самий метод, шлях і тіло, лічильник times seen перехопленого запиту збільшується (один лише Stripe повторює до восьми разів), а новий рядок не додається.
Результати
| Результат | Що отримав відправник | Значення |
|---|---|---|
accepted | 202 | Перевірено й опубліковано як подію. |
bad_signature | 401 | Підпис не пройшов перевірку секретом джерела. |
not_json | 400 | Тіло не є обʼєктом JSON. |
rate_limited | 429 | Перевищено частоту публікацій робочого простору. |
over_quota | 402 | Робочий простір вичерпав місячний обсяг доставок. |
too_large | 413 | Payload перевищує 256 KiB. |
unknown_event_type | 422 | Тип не зареєстровано, а політика типів подій — Strict. |
invalid_payload | 422 | Payload не відповідає JSON Schema свого типу події. |
duplicate | 409 | Ідентифікатор події провайдера вже було прийнято з іншим тілом. |
bad_signature — звична перша знахідка: у джерело вставлено не той секрет або проксі перед вашим провайдером переписав тіло. Порівняйте перехоплені заголовки з журналом доставок самого провайдера.
Деякі відмови не записуються: запит до невідомого або вимкненого джерела (немає джерела, для якого його зберігати), запит понад ліміт 512 KiB і запит, відхилений лімітом проти флуду для джерела ще до перевірки підпису. Таблиця статусів на сторінці Джерела показує, що в кожному з цих випадків бачить відправник.
Скільки зберігаються перехоплені запити
Джерело зберігає 500 останніх перехоплених запитів, і кожен видаляється через 7 днів після того, як його бачили востаннє. Щоб видалити запит раніше, скористайтеся консоллю або DELETE /v1/captures/{id}.
Читання через API
# The latest captures for one source, refusals only
curl -s "https://webhooks.nimbusnexus.net/v1/captures?source_id=src_…&outcome=bad_signature" \
-H "Authorization: Bearer $READ_KEY"
# One capture with its headers and body (base64, since a body may not be UTF-8)
curl -s https://webhooks.nimbusnexus.net/v1/captures/cap_… \
-H "Authorization: Bearer $READ_KEY"Список не містить тіл; щоб отримати headers_raw і body_base64, запитайте перехоплений запит за ідентифікатором. Усі операції з перехопленими запитами описано в довіднику API.
Чим це не є
Перехоплені запити — це не request bin, який ви створюєте й на який надсилаєте довільний трафік: вони записують лише те, що надходить до ваших власних джерел. Якщо потрібен URL, що записує будь-який надісланий на нього HTTP-запит, використовуйте Request Bins.
Що далі
- Джерела — як створити джерело і що означає кожна відмова.
- Типи подій — чому запит може бути відхилено як
unknown_event_type. - Доставки та повтори — що далі відбувається з прийнятим запитом.