filestack-webhook-setup

Filestack Webhook Setup

Webhook Event Types

Event	When it fires
fp.upload	File successfully uploaded and stored
fp.converse	Image conversion (filepicker-converse) completed
fp.delete	File deleted
fp.overwrite	File overwritten
fp.video_converse	Video conversion completed
fp.scan	Antivirus scan completed
fp.export	File exported to cloud storage
fs.workflow	Workflow pipeline completed

Register a Webhook URL

Webhook registration is done through the Filestack Developer Portal UI — there is no public REST endpoint for creating webhooks. Walk the user through:

1. Sign in at https://dev.filestack.com/
2. Open the app whose events you want to receive
3. Navigate to Webhooks in the left nav
4. Click Add Webhook, paste the receiver URL (https://yourdomain.com/filestack-webhook)
5. Select the events to subscribe to (e.g. fp.upload, fp.video_converse)
6. Copy the generated webhook secret — it appears only once, you'll need it for signature verification (see below)

If the user asks for an API-based registration flow, explain that this isn't currently exposed publicly — they have to use the portal. (There is an internal admin endpoint but it is gated by admin auth and not customer-accessible.)

Webhook Payload Shape

{
  "id": 30813791,
  "action": "fp.upload",
  "timestamp": 1710000000,
  "text": {
    "container": "filestack-uploads",
    "url": "https://cdn.filestackcontent.com/abc123XYZ",
    "filename": "image.jpg",
    "client": "Computer",
    "key": "abc123XYZ",
    "type": "image/jpeg",
    "status": "Stored",
    "size": 102400
  }
}

Signature Verification

Filestack signs webhooks with HMAC-SHA256 using a per-webhook secret (created in the Developer Portal when configuring the webhook — this is NOT the app secret). The signature covers "{timestamp}.{body}" — the FS-Timestamp header value, a dot, and the raw request body.

Headers sent by Filestack: