Протокол webhook

Контракт повідомлень webhook — формат даних, підпис HMAC, повтори та запобіжний вимикач.

Коли завдання завершується (completed, failed чи cancelled), ми надсилаємо повідомлення POST на callback_url вашої інсталяції. Ця сторінка описує контракт повідомлень; практичний посібник із кодом перевірки ви знайдете в навчальному матеріалі про отримання результатів.

Формат повідомлення

{
  "event": "job.completed",
  "delivered_at": "2026-06-03T08:00:00.000Z",
  "job": {
    "id": "00000000-0000-0000-0000-0000000000a1",
    "status": "completed",
    "order_id": "00000000-0000-0000-0000-000000000099",
    "completed_at": "2026-06-03T07:59:40.000Z",
    "error": null
  },
  "outputs": [
    {
      "url": "https://…?token=…",
      "type": "image/jpeg",
      "width": 1024,
      "height": 1280
    }
  ],
  "external_metadata": { "your": "tag" }
}

event — job.completed, job.failed чи job.cancelled.
outputs[].url — адреси для завантаження, дійсні щонайменше 7 днів; свіжі отримаєте через POST /jobs/{id}/refresh-url.
external_metadata — повертає рівно те, що ви надіслали під час створення сесії.

Підпис

Кожне повідомлення містить заголовок:

X-Qamera-Signature: t=<unix-час>,v1=<hmac_sha256_hex>

Підписується рядок <t>.<сире-body> секретом HMAC інсталяції (алгоритм HMAC-SHA256, результат у hex). Відхиляйте повідомлення, у яких t старше за 5 хвилин. Готові функції перевірки в Node.js і PHP ви знайдете в навчальному матеріалі.

Вікно заміни секрету

Після заміни секрету через POST /installations/{id}/rotate-hmac попередній секрет діє ще 48 годин. У цьому вікні повідомлення мають два сегменти v1= — по одному на кожен секрет; прийміть будь-який із них:

X-Qamera-Signature: t=1746777600,v1=e3b0…,v1=44a0…

Після завершення вікна ми підписуємо лише новим секретом.

Гарантії надійності

До 8 спроб доставлення, із наростаючим інтервалом (з випадковим розкидом), щонайбільше 1 година між спробами.
5 послідовних невдалих доставлень призупиняють надсилання на 30 хвилин (запобіжний вимикач).
3 такі цикли призупиняють інсталяцію — відновлення вимагає адміністратора.
Після вичерпання спроб повідомлення отримує статус abandoned і його можна надіслати повторно через POST /webhooks/{delivery_id}/replay.

Ваш ендпойнт має:

Відповідати будь-яким статусом 2xx на прийняті повідомлення.
Обробляти ідемпотентно — після повільної відповіді 200 ми можемо повторити надсилання вже доставленого повідомлення.
Записувати (event, job.id, delivered_at) для діагностики — уже підтверджені повідомлення ми не надсилаємо повторно з власної ініціативи.