An event for every stage of the file lifecycle
Each event fires at a specific point and carries a payload describing the file and the result. Turning on webhook notifications is a dashboard setting rather than a build.
| Event | Fires when | Typical payload |
|---|---|---|
| fp.upload | An upload completes | File handle, URL, size, MIME type |
| fp.converse | A file conversion finishes | Source and output file info |
| fp.video_converse | A video conversion completes | Output formats, status |
| fp.delete | A file is deleted | Handle, timestamp |
| fp.overwrite | A file is overwritten | Handle, new metadata |
| fp.scan | A virus scan resolves | Scan result / verdict |
| fp.export | An export completes | Destination info |
| fs.workflow | A workflow run resolves | Per-task results |
An endpoint, an event type, and a secret
Paste the URL, pick the events it receives, generate the signing secret.
Verify every payload
Webhook security comes down to one habit, webhook signature verification on every request. Every payload carries FS-Signature and FS-Timestamp. Recompute the HMAC and compare, and you know the event is authentic and fresh.
function verify(req, secret) {
const sig = req.headers['fs-signature'];
const ts = req.headers['fs-timestamp'];
const digest = crypto
.createHmac('sha256', secret)
.update(ts + req.rawBody)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(digest), Buffer.from(sig));
}
def verify(headers, raw_body, secret):
sig = headers['FS-Signature']
ts = headers['FS-Timestamp']
digest = hmac.new(
secret.encode(),
(ts + raw_body).encode(),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(digest, sig)
Search and moderate uploads
Sign the timestamp, a dot, then the raw body exactly as it arrived. Run these numbers yourself with the secret SAMPLE_WEBHOOK_SECRET_DO_NOT_USE.
1785812400
# FS-Signature
aa759bf08e534c0f6078194120
91d4932d9bd6923655150be52d
6d066c72c2d4
# body
{ "id": 423984,
"action": "fp.upload",
"timestamp": 1785812400,
"text": {
"url": "https://cdn.filestackcontent
.com/UZ9TFxQAmAHdNFEx8hzw",
"filename": "user-avatar-outdoor.png",
"size": 1467090,
"mimetype": "image/png",
"status": "Stored" } }
Verify the bytes you received, never a re-serialized object. One changed character moves the digest.
# for 9kQx7RtTSaWvNmPd2fLb
expected a2b26c41d4f54c15f0767e7a14
64af5b9cae562b647e357cc30c
6abb006ee1e8
received aa759bf08e534c0f6078194120
91d4932d9bd6923655150be52d
6d066c72c2d4
valid false
Verify the bytes you received, never a re-serialized object. One changed character moves the digest.
What teams build with webhooks
Update your database the moment an upload lands
When the fp.upload webhook arrives, write the file handle and metadata to your database immediately.
Gate publication on scan and moderation
Wait for fp.scan and moderation results before flipping a file to public. The webhook is the signal that it is safe to publish.
Kick off downstream processing
When fp.video_converse fires, start the next step (generate thumbnails, notify subscribers, or update the player) knowing the transcode is done.
Sync asset state into your DAM or CMS
Use lifecycle events to keep an external DAM or CMS in sync as files are added, overwritten, or deleted.
Webhooks plus Workflows
Together they replace a queue-and-worker build. The Workflow does the processing (scan, moderate, transcode), and the fs.workflow webhook tells you it is done, with per-task results. That is the whole webhook integration, one webhook endpoint and one signature check, with the queue and the polling on our side.
Testing and reliability
Retry on failure
Filestack retries delivery when your endpoint returns a non-2xx response, so a brief outage on your side still ends with the event delivered.
Test the signing helper
Use the signing helper to generate a valid signature locally and confirm your verification code accepts genuine payloads and rejects tampered ones. Both halves matter.
Configure in the dashboard
Register and manage webhook endpoints from the developer dashboard. Point events at the URL you control.
Frequently Asked Questions
What is a file upload webhook?
A file upload webhook is an HTTP notification sent to your endpoint the moment a file event occurs, such as an upload completing. Instead of polling for status, your backend receives a signed POST with the event details and acts on it immediately.
How do I verify a Filestack webhook signature?
Filestack signs each webhook with the FS-Signature and FS-Timestamp headers. Webhook signature verification means computing an HMAC-SHA256 of the timestamp concatenated with the raw request body using your webhook secret, then comparing it to FS-Signature. A match proves the event came from Filestack and was not tampered with or replayed.
What events does Filestack send?
Filestack emits events across the file lifecycle, including fp.upload, fp.converse, fp.video_converse, fp.delete, fp.overwrite, fp.scan, fp.export, and fs.workflow. Each fires at a specific stage and carries a payload describing the file and the result.
Can I get notified when a video conversion finishes?
Yes. The fp.video_converse event fires when a video conversion completes, so you can kick off downstream processing or update your UI without polling the conversion status.
Listen for every file event
Wire signed file-event webhooks into your backend with a free API key.