Як спроєктувати вихідні вебхуки, які зручно приймати іншим сервісам?

Вебхук - HTTP-запит, який ваш сервіс надсилає на URL клієнта, коли щось сталося: замовлення оплачене, вакансію опубліковано. Клієнт не опитує API, а отримує подію сам.

Що надсилати:

{
  "id": "evt_01J9Z3K8",
  "type": "order.paid",
  "created_at": "2026-10-04T10:15:00Z",
  "api_version": "2026-09-01",
  "data": {
    "object": { "id": 42, "status": "paid", "total": "1250.00", "currency": "UAH" }
  }
}

• id події - унікальний: одержувач за ним відкидає дублікати;
• type - назва події у форматі ресурс.дія; клієнт підписується лише на потрібні;
• час події - щоб одержувач міг розібратися з порядком;
• версія формату - щоб змінювати структуру, не ламаючи наявних інтеграцій;
• дані: або повний знімок об'єкта («товстий» вебхук), або лише ідентифікатор («тонкий», одержувач сам запитує актуальний стан через API).

Обов'язкові складники надійного вебхука:

• підпис запиту (HMAC з секретом одержувача) і мітка часу - щоб одержувач перевірив, що запит від вас і не повторений;
• HTTPS для URL одержувача;
• доставка «щонайменше один раз»: при помилці чи тайм-ауті - повторні спроби з наростаючою затримкою. Одержувач має бути готовим до дублікатів;
• швидка відповідь: одержувач підтверджує прийом кодом 2xx одразу, а обробляє асинхронно. Документуйте тайм-аут (кілька секунд);
• журнал доставок у кабінеті: які події пішли, з яким кодом відповіді, кнопка «надіслати ще раз».

Відправлення в Laravel - лише через чергу. HTTP-запит до чужого сервера в обробнику запиту користувача - затримки й падіння, якщо одержувач повільний чи недоступний. Готове рішення - пакет spatie/laravel-webhook-server: черга, підпис, повтори з затримкою, події про невдалі доставки.

Документація для одержувачів: перелік типів подій із прикладами, як перевіряти підпис, політика повторів, тестові події з кабінету.

Докладніше в документації: Вебхуки Stripe