{"canonical_url":"https://engineer.company/uk/glossary/webhook/","content_markdown":"# вебхук\n\n## Що це таке\n\nВебхук — це HTTP-запит, який один сервіс надсилає іншому тієї миті, коли в нього\nщось стається: проходить платіж, оплачено рахунок, завершилося довге завдання.\nСторона-отримувач заздалегідь реєструє URL, а відправник надсилає туди опис\nкожної події методом POST. Специфікація Standard Webhooks називає вебхуки «a\ncommon name for HTTP callbacks» і описує їх як спосіб, у який сервіси\nповідомляють одне одного про події. Трапляється також написання через дефіс,\nвеб-хук, а в англомовній документації Stripe, GitHub і специфікації слово пишуть\nлатиницею й разом: webhook.\n\nСпецифікація також описує вебхук як частину API сервісу, такий собі API, що\nпрацює навпаки. Зазвичай клієнт звертається до сервісу, коли йому щось потрібно.\nЗ вебхуком сервіс звертається до клієнта, коли має новини. У типовій\nAPI-інтеграції обидві сторони запускають HTTP-сервери: одна для отримання\nвикликів API, інша — для вебхуків. Сервіс може також надсилати вебхуки, не\nпропонуючи власного API для запитів. Відправника\nспецифікація називає producer, отримувача — consumer, а URL, який реєструє\nотримувач, — це його кінцева точка для вебхуків (webhook endpoint).\n\nСпецифікація рекомендує HTTP POST із тілом JSON, але не вимагає певного формату\nчи структури payload. У запропонованому тілі є `type`, записаний через крапки й\nупорядкований ієрархічно, наприклад `invoice.paid`; `timestamp` — час, коли\nподія сталася, в ISO 8601; і дані події або в `data`, або на верхньому рівні.\nДодаткові метадані можуть бути в обох місцях. Метадані доставки йдуть у\nзаголовках: `webhook-id` ідентифікує подію, `webhook-timestamp` фіксує час цієї\nспроби в секундах Unix, а `webhook-signature` підтверджує її автентичність.\nStripe і GitHub мають власні назви заголовків, серед них `Stripe-Signature` і\n`X-Hub-Signature-256`, а правила перевірки в них різні: Stripe підписує мітку\nчасу спроби разом із тілом, тоді як HMAC GitHub охоплює лише тіло.\n\nPayload буває повним, коли містить увесь змінений об'єкт, або тонким, коли в\nньому мало що є, крім ідентифікатора, і решту отримувач сам забирає через API.\nСпецифікація зважує обидва варіанти. Повний payload заощаджує отримувачу\nдодаткові виклики API. Тонкий означає менше даних для формування й надсилання,\nбільше гнучкості й більше простору для змін надалі, бо тонкий payload завжди\nможна розширити до повного, а навпаки — ні. До того ж він робить доступ до даних\nпридатним для аудиту, бо отримувач мусить явно запитати те, що читає. Хай там\nяк, специфікація радить тримати payload невеликим, зазвичай до 20 кБ. Stripe\nпропонує тонкий формат і позначає його як рекомендований.\n\n## Чому це важливо\n\nБез вебхуків система, якій треба знати про зміну деінде, мусить вдаватися до\nопитування (polling): питати знову й знову, здебільшого лише щоб почути, що\nнічого не сталося, і все одно дізнатися про зміну тільки під час наступного\nопитування. Вебхук розвертає це. Сервіс, що знає про подію, звертається один раз\n— тоді, коли вона стається. Саме так платіжні провайдери, сервіси хостингу коду\nй поштові провайдери повідомляють системи, побудовані на них.\n\nЦей розворот має ціну, і здебільшого її платить сторона-отримувач. Її кінцева\nточка — публічний URL, на який будь-хто в інтернеті може надіслати POST, і ніщо\nу вхідному запиті не показує, хто його надіслав, тому специфікація робить\nперевірку автентичності обов'язковою для будь-якої безпечної реалізації.\nДоставку повторюють, доки отримувач не відповість статусом 2xx або політика\nдоставки не припинить спроби, тож та сама\nподія може надійти більше ніж один раз; Stripe попереджає, що кінцеві точки\nзрідка можуть отримувати дублікати. Порядок теж не гарантовано: Stripe прямо\nпише, що не гарантує надходження подій у тому порядку, в якому їх згенеровано.\n\nВідправник, зі свого боку, мусить і далі пробувати. Специфікація рекомендує\nрозклад повторних спроб на кілька днів з експоненційною затримкою і невеликим\nвипадковим розкидом (jitter). У її прикладі десять спроб, остання — через 75\nгодин, 35 хвилин і 5 секунд після першої. Stripe повторює спроби до трьох днів у\nlive mode. Отримувач, який повернувся в межах цього вікна, наздожене все сам;\nпісля нього Stripe дає змогу вручну повторно надіслати подію впродовж 15 днів\nпісля її створення або впродовж 30 днів через свій CLI. Якщо доставка довго не\nвдається, специфікація радить відправникові повідомити отримувача іншим каналом,\nнаприклад електронною поштою, і вимкнути кінцеву точку.\n\n## Як це виглядає на практиці\n\nОсь заголовки доставки у форматі специфікації. Ідентифікатор, мітка часу й\nпідпис — це приклади значень із самої специфікації; значення `Host` і шлях\nвигадані:\n\n```http\nPOST /webhooks/billing HTTP/1.1\nHost: example.com\nContent-Type: application/json\nwebhook-id: msg_2KWPBgLlAfxdpx2AI54pPJ85f4W\nwebhook-timestamp: 1674087231\nwebhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=\n```\n\nА ось тіло, тонкий payload з тієї ж специфікації, тут відформатований для\nчитабельності. Під час реального надсилання специфікація радить передавати його\nмініфікованим:\n\n```json\n{\n  \"type\": \"contact.created\",\n  \"timestamp\": \"2022-11-03T20:26:10.344522Z\",\n  \"data\": {\n    \"id\": \"1f81eb52-5198-4599-803e-771906343485\"\n  }\n}\n```\n\nПрефікс `v1` позначає симетричний підпис: HMAC-SHA256 від ідентифікатора події,\nмітки часу й тіла, з'єднаних крапками, обчислений із секретним ключем,\nунікальним для кінцевої точки. Оскільки ідентифікатор і мітку часу підписують\nразом із тілом, жодне з них не можна змінити, не зламавши підпис. Специфікація\nдопускає й асиметричні підписи ed25519, позначені `v1a`, і рекомендує їх, коли\nви не контролюєте безпеку і відправника, і отримувача.\n\nGitHub теж підписує свої доставки HMAC-SHA256, кладе шістнадцятковий дайджест у\n`X-Hub-Signature-256` із префіксом `sha256=` і публікує секрет, payload і\nпідпис, на яких можна перевірити верифікатор. Ось верифікатор на Python,\nперевірений саме на цьому прикладі:\n\n```python\nimport hashlib\nimport hmac\n\n\ndef verify(body: bytes, secret: str, header: str) -\u003e bool:\n    mac = hmac.new(secret.encode(\"utf-8\"), body, hashlib.sha256)\n    expected = \"sha256=\" + mac.hexdigest()\n    return hmac.compare_digest(expected, header)\n\n\nsecret = \"It's a Secret to Everybody\"\nheader = (\n    \"sha256=757107ea0eb2509fc211221cce984b8a\"\n    \"37570b6d7586c22c46f4379c8b043e17\"\n)\nprint(verify(b\"Hello, World!\", secret, header))  # True\nprint(verify(b\"Hello, World! \", secret, header))  # False\n```\n\nОдного пробілу в кінці тіла достатньо, щоб перевірка не пройшла.\n`hmac.compare_digest` працює однаковий час, хоч рядки розходяться на початку,\nхоч у кінці; документація GitHub наголошує, що підписи ніколи не можна\nпорівнювати звичайним `==`. Надійний обробник далі діє в чіткому порядку:\nпрочитати сирі байти, перевірити підпис саме над цими байтами, переконатися, що\nмітка часу спроби не застара, якщо відправник її підписує, перевірити, чи не\nтраплявся вже цей ідентифікатор події,\nпоставити подію в чергу й відповісти 2xx. Справжня робота відбувається потім.\nStripe наводить приклад: повернути 200, перш ніж позначати рахунок клієнта як\nоплачений у бухгалтерській системі.\n\nДва проєкти з портфоліо цього сайту мають справу з вебхуками з боку отримувача.\nУ проєкті про\n[права доступу через Stripe та in‑app](/uk/portfolio/built-stripe-and-in-app-purchase-entitlements/)\nпідписка, серед іншого, мусить пережити вебхук, що прийшов двічі, і вебхук, що\nприйшов не в тому порядку. У\n[поштовій системі з failover і журналом доставки](/uk/portfolio/built-email-with-failover-and-delivery-logging/)\nвхідні вебхуки повідомляють, що кожен провайдер зробив із листом, а проєкт\nфіксує і те, що надіслано, і те, що повернулося, — у журналі надсилань і в\nтаблиці подій доставки.\n\n## Де виникають проблеми\n\n**Підпис ніколи не збігається.** Типова причина: фреймворк отримувача розбирає\nJSON-тіло, а код знову серіалізує його, перш ніж обчислити HMAC. Специфікація\nназиває це дуже поширеною помилкою: серіалізація JSON відрізняється в різних\nреалізаціях, і один зайвий пробіл робить підпис недійсним. Stripe потребує\nсирого тіла з тієї ж причини й попереджає, що будь-яка зміна в ньому зриває\nперевірку. GitHub додає, що проксі чи балансувальник навантаження перед кінцевою\nточкою не повинні змінювати payload або заголовки і що payload слід обробляти як\nUTF-8. Обчислюйте підпис над байтами точно такими, якими вони надійшли, ще до\nтого, як щось їх розбере.\n\n**Та сама подія надходить двічі.** Дублікати дають і повторні спроби, і збої\nмережі. За специфікацією `webhook-id` лишається тим самим під час кожної\nповторної спроби для події й слугує ключем ідемпотентності; її приклад — тримати\nідентифікатори в Redis п'ять хвилин. Stripe радить записувати ідентифікатори\nоброблених подій і пропускати ті, що вже траплялися. Stripe також зазначає, що\nіноді створюються й надсилаються два окремі об'єкти Event; їх можна розпізнати\nза ідентифікатором об'єкта в `data.object` разом із типом події. Заголовок\n`X-GitHub-Delivery` від GitHub лишається тим самим, коли доставку надсилають\nповторно. Обробка має бути ідемпотентною, щоб друга доставка нічого не\nзмінювала.\n\n**Перехоплену доставку відтворюють повторно.** Дійсний підпис лишається дійсним,\nтож зловмисник, який перехопив одну доставку, може надіслати її знову. Саме тому\nмітку часу підписують: специфікація каже відхиляти `webhook-timestamp`, що\nвиходить за межі допустимого відхилення. Бібліотеки Stripe за замовчуванням\nдопускають п'ять хвилин, Stripe попереджає, що відхилення 0 повністю вимикає\nперевірку, і рекомендує NTP, щоб годинник сервера йшов точно. І Stripe, і\nспецифікація ставлять нову мітку часу на кожну повторну спробу, тож вік\nвідлічують від цієї спроби, а не від початкової події; затримана спроба все ще\nможе вийти за межі допустимого відхилення. Тримайте вже бачені ідентифікатори\nщонайменше стільки, скільки триває допустиме відхилення, — і все, що відтворять\nповторно в межах цього вікна, буде виявлено як дублікат.\n\n**Події надходять не в тому порядку.** Приклад від Stripe: створення підписки\nможе породити `customer.subscription.created`, `invoice.created`, `invoice.paid`\nі, якщо є списання, `charge.created`, і ніщо не гарантує, що вони надійдуть саме\nв такому порядку. Знімкові події (snapshot events) Stripe записують `created` у\nцілих секундах, тож різні події можуть мати однакову мітку часу, і Stripe радить\nне використовувати її, щоб упорядковувати події чи виявляти дублікати. Надійний\nпідхід — сприймати подію як сповіщення, що щось змінилося, і перед тим як діяти,\nотримувати поточний стан об'єкта через API.\n\n**Обробник надто повільний.** GitHub очікує 2xx упродовж 10 секунд; після цього\nGitHub розриває з'єднання й зараховує доставку як невдалу. Специфікація\nрекомендує тайм-аут запиту десь від 15 до 30 секунд. Обробник, який виконує\nсправжню роботу, перш ніж відповісти, натрапляє на тайм-аут, відправник повторює\nспробу, і робота виконується двічі. І Stripe, і GitHub рекомендують чергу.\nStripe вказує на пік на початку місяця, коли поновлюються всі підписки.\n\n**Зараховується лише 2xx.** Усе інше вважається невдачею, зокрема й 3xx, і для\nспецифікації, і для Stripe, тож кінцева точка, яку перенесли за переспрямування,\nпровалює кожну доставку, доки зареєстрований URL не оновлять. Кільком кодам\nспецифікація надає значення для відправника: `410 Gone` означає, що кінцеву\nточку треба вимкнути, 429, 502 чи 504 — що слід сповільнитися, а заголовок\n`retry-after` має визначати наступну спробу.\n\n**Для відправника URL — ворожі вхідні дані.** Клієнти можуть указати будь-який\nURL, і сервери відправника його викличуть. Специфікація називає системи вебхуків\nособливо вразливими до підробки запитів на боці сервера (server-side request\nforgery, SSRF): URL, що вказує на внутрішню адресу, змушує відправника\nзвертатися до власної мережі. Її порада — пропускати всі запити вебхуків через\nпроксі, який відфільтровує внутрішні IP-адреси, як-от smokescreen від Stripe, і\nзапускати воркери вебхуків у приватній підмережі, яка не має доступу до\nвнутрішніх сервісів.\n\n## Що почитати далі\n\n- [Standard Webhooks specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md)\n  — версія 1.0.0: структура payload, алгоритм підпису, заголовки, розклад\n  повторних спроб, обробка кодів стану й SSRF.\n- [Receive Stripe events in your webhook endpoint](https://docs.stripe.com/webhooks)\n  — тонкі та знімкові payload, повторні спроби, дублікати, події не в тому\n  порядку й захист від повторного відтворення.\n- [Best practices for using webhooks](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks)\n  — список GitHub: підписка на мінімум подій, секрет вебхука, HTTPS, відповідь\n  упродовж 10 секунд, повторна доставка й `X-GitHub-Delivery`.\n- [Validating webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)\n  — `X-Hub-Signature-256`, порівняння за сталий час і тестовий приклад, на якому\n  можна перевірити верифікатор.\n\n\u003chttps://engineer.company/uk/glossary/webhook/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"Як сервіс повідомляє ваш сервер, що щось сталося, як виглядає підписана доставка і чому приймальна сторона має бути готова до дублікатів і повторних спроб.","formats":{"gemtext":"https://engineer.company/uk/glossary/webhook/index.gmi","gopher":"https://engineer.company/uk/glossary/webhook/gophermap","html":"https://engineer.company/uk/glossary/webhook/","json":"https://engineer.company/uk/glossary/webhook/index.json","markdown":"https://engineer.company/uk/glossary/webhook/index.md","pdf":"https://engineer.company/uk/glossary/webhook/index.pdf"},"kind":"page","language":"uk","title":"Що таке вебхук?","url":"https://engineer.company/uk/glossary/webhook/","version":1}