Webhooks

Receive real-time events for image lifecycle, quota changes, and key revocations.

FastPic delivers webhook events to a URL you configure in the dashboard. Events arrive as JSON over POST with an HMAC signature you verify before trusting the payload.

Events

FastPic emits the following event types:

Event	Description
image.created	A new image was uploaded via POST /v1/images.
image.deleted	An image was soft-deleted via DELETE or dashboard.
api_key.revoked	An API key was revoked.
quota.warned	Storage quota crossed 80% of the plan limit.
quota.exceeded	Storage quota was exceeded; uploads are blocked.

Delivery format

Each event is delivered as a POST request to your configured 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": { ... } }
}

Signature verification

Verify every webhook before processing it. The X-FastPic-Signature header contains a timestamp and HMAC-SHA256 of `{timestamp}.{rawBody}` using your endpoint's signing secret.

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
}

Retries

FastPic considers a webhook delivered when your endpoint returns 2xx within 10 seconds. Otherwise we retry with exponential backoff: 1m, 5m, 30m, 2h, 6h, 24h. After 6 failed attempts the endpoint is auto-disabled and you receive an email notification.

Configuring an endpoint

Add a webhook endpoint at app.fastpic.pro/keys → Webhooks. Each endpoint gets its own signing secret. Test signatures via the dashboard's test-event button before relying on the integration.