Тестування Webhooks: посібник розробника

Webhooks є основою комунікації в реальному часі між сервісами. Замість постійного опитування API, webhook дозволяє одному серверу надсилати дані іншому, щойно щось відбувається — оплата завершена, коміт запушено або форму відправлено. Для розробників, які створюють інтеграції, вміння тестувати webhooks локально та в staging-середовищах є необхідною навичкою.

На відміну від стандартного REST API виклику, який ви ініціюєте з коду, webhook вимагає, щоб відправляючий сервер досяг вашого ендпоінту. Під час локальної розробки ваша машина не є загальнодоступною в інтернеті. Це означає, що сервіс-відправник не може доставити payload на localhost:3000. Вам також потрібно симулювати точні заголовки, формат підпису та структуру JSON, які надсилає реальний сервіс.

Кілька інструментів заповнюють розрив між localhost та публічним інтернетом. ngrok створює безпечний тунель до вашого локального сервера і надає публічну HTTPS URL. Cloudflare Tunnel пропонує подібну можливість, інтегровану з мережею Cloudflare. localtunnel — легка open-source альтернатива. Кожен із цих інструментів пересилає вхідні webhook запити на ваш локальний сервер.

Webhook ендпоінт, відкритий для інтернету, може отримувати запити від будь-кого. Щоб перевірити, що запит дійсно від очікуваного відправника, продакшн webhooks використовують HMAC підписи. Сервер-відправник обчислює хеш тіла payload за допомогою спільного секрету і включає його в заголовок на кшталт X-Hub-Signature-256 (GitHub) або Stripe-Signature (Stripe). Ваш сервер повинен перевирахувати хеш і порівняти його. Ніколи не довіряйте даним webhook без перевірки підпису.

При тестуванні webhooks із браузерного інструменту CORS стає перешкодою. Браузери блокують відповіді від серверів, які явно не дозволяють ваш origin через заголовок Access-Control-Allow-Origin. Щоб обійти це, направляйте тестові запити через серверний проксі або використовуйте наш експорт cURL команд для тестування з терміналу.