FastPic

Webhooks

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

FastPic доставляє webhook-події на URL, налаштований у дашборді. Події надходять як JSON через POST з HMAC-підписом, який необхідно перевірити перед обробкою payload.

Події

FastPic надсилає такі типи подій:

EventDescription
image.createdA new image was uploaded via POST /v1/images.
image.deletedAn image was soft-deleted via DELETE or dashboard.
api_key.revokedAn API key was revoked.
quota.warnedStorage quota crossed 80% of the plan limit.
quota.exceededStorage quota was exceeded; uploads are blocked.

Формат доставки

Кожна подія доставляється як POST-запит на налаштований URL:

webhook.http
POST /your/webhook HTTP/1.1
Host: example.com
Content-Type: application/json
X-FastPic-Event: image.created
X-FastPic-Delivery: 8a4c6f12-aabb-4c1f-9d5b-aaaaaaaaaaaa
X-FastPic-Signature: t=1730476800,v1=5257a8...
 
{
  "id": "evt_a1b2c3",
  "type": "image.created",
  "created": 1730476800,
  "data": { "object": { ... } }
}

Перевірка підпису

Перевіряйте кожен webhook перед обробкою. Заголовок X-FastPic-Signature містить timestamp і HMAC-SHA256 рядка `{timestamp}.{rawBody}`, підписаного секретом signing secret вашого endpoint'а.

verify.ts
import { createHmac } from 'crypto'
 
export const verify = (header: string, body: string, secret: string) => {
  const [ts, sig] = header.split(',').map(p => p.split('=')[1])
  const expected = createHmac('sha256', secret).update(`${ts}.${body}`).digest('hex')
  return sig === expected
}

Повторні спроби

FastPic вважає webhook доставленим, якщо endpoint повернув 2xx протягом 10 секунд. Інакше виконуються повторні спроби з експоненційною затримкою: 1 хв, 5 хв, 30 хв, 2 год, 6 год, 24 год. Після 6 невдалих спроб endpoint автоматично вимикається, і ви отримуєте email-повідомлення.

Налаштування endpoint'а

Додайте webhook endpoint у дашборді: app.fastpic.pro/keys → Webhooks. Кожен endpoint отримує власний signing secret. Протестуйте підписи через кнопку тестової події в дашборді, перш ніж покладатися на інтеграцію.