Flikly Developers
Operations

Webhooks

Register HTTPS endpoints to receive job.completed and job.failed events. Manage endpoints at https://api.flikly.ai/api/v1/developer/webhooks or the portal.

Create endpoint

curl -s -X POST "https://api.flikly.ai/api/v1/developer/webhooks" \
  -H "Authorization: Bearer $FLIKLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/flikly/webhooks",
    "description": "Production",
    "events": ["job.completed", "job.failed"]
  }'

The response includes secret once — store it for signature verification.

Event types

  • job.completed — terminal success; includes API paths to fetch results (not signed URLs)
  • job.failed — terminal failure with safe error message
  • webhook.test — sent by POST /webhooks/{id}/test

Payload example (job.completed, video)

{
  "id": "evt_abc123",
  "type": "job.completed",
  "created_at": "2026-05-24T12:00:00.000Z",
  "data": {
    "job": {
      "id": "video_job_xyz",
      "type": "video",
      "status": "completed",
      "result_url": "/api/v1/developer/video-jobs/video_job_xyz/result",
      "asset_id": "asset_out123"
    }
  }
}

Signature headers

  • Flikly-Webhook-Id
  • Flikly-Webhook-Event
  • Flikly-Webhook-Timestamp (Unix seconds)
  • Flikly-Webhook-Signature — v1=<hex> HMAC-SHA256 of "timestamp.rawBody"

Verification

Read the raw request body (do not parse JSON first). Reject timestamps older than 5 minutes. Compare signatures with a timing-safe equals function. See developers/examples/node/verify-webhook-signature.js and developers/examples/python/verify_webhook_signature.py.

Retries

Failed deliveries retry with exponential backoff (up to 6 attempts). Retries require DEVELOPER_WEBHOOK_DELIVERY_ENABLED and the Flikly webhook retry scheduler (or ops manual run). Your endpoint should respond 2xx quickly; fetch job results separately using the paths in the payload.

Security

  • Webhook payloads never include presigned storage URLs or provider IDs.
  • Only HTTPS URLs are accepted.
  • Team plan: up to 3 webhook endpoints per organization.

Scopes: webhooks:read, webhooks:write.