How to Integrate Fast.io Webhooks with Temporal.io

Fast.io webhooks send HTTP POST requests to your endpoint when key file events happen. These include file uploads, modifications, deletions, and access events. Each payload contains details like file ID, workspace ID, user ID, and timestamps.

The event types cover common triggers for processing pipelines. For example, an upload event fires right after a file lands in your workspace. This is perfect for kicking off analysis, transcoding, or validation tasks.

Payloads follow a standard JSON structure. Here's a typical upload event:

{
  "eventType": "upload",
  "workspaceId": "1234567890123456789",
  "fileId": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4",
  "fileName": "large-video.mp4",
  "fileSize": 2457600000,
  "userId": "9876543210987654321",
  "timestamp": "2026-02-24T10:30:00Z",
  "eventId": "evt-abc123def456"
}

Fast.io signs payloads for verification. Check the Fastio-Signature header against a shared secret from your workspace settings. This prevents spoofing.

Webhooks reduce polling. Instead of checking for new files every minute, you react instantly to changes. For agentic teams, this means workflows start the moment data arrives.

Temporal.io handles long-running, fault-tolerant workflows. Workflows guarantee completion despite failures. If a worker crashes mid-processing of a 10GB file, Temporal replays from the last checkpoint.

According to Temporal documentation, workflows provide at-least-once execution semantics. This fits file processing where duplicates are rare but idempotency matters.

Fast.io supports files up to hundreds of GB. Standard handlers fail on large uploads or network blips. Temporal retries activities like downloads or transformations indefinitely or until success.

Common use case: video pipeline. Upload triggers workflow to download, transcode to HLS, generate thumbnails, then upload results back to Fast.io. If transcoding fails due to memory pressure, retry happens automatically.

Other benefits include timeouts, cancellation, and visibility. Track progress in Temporal Web UI.

Build Durable File Pipelines Today

Fast.io's free agent tier gives you 50GB storage, 5,000 monthly credits, and full API access. Pair with Temporal for production-grade processing.

Sign Up Free

The flow works like this:

1. File uploads to Fast.io workspace.
2. Fast.io POSTs webhook to your endpoint (e.g. Vercel function or Express server).
3. Handler verifies signature, extracts event data.
4. Handler starts Temporal workflow using Workflow ID based on event ID for idempotency.
5. Workflow orchestrates activities: download file via Fast.io API, process, store results.

Use signals for mid-workflow updates. For example, signal completion back to Fast.io comments.

Diagram (conceptual):

Fast.io → Webhook → Temporal Worker → Activities (Download, Process, Upload)

Deploy webhook as serverless for scale. Temporal Cloud handles orchestration.

Gather these before starting:

• Fast.io account (free agent tier: 50GB storage, 5 workspaces).
• Temporal development cluster (docker run temporalio/auto-setup).
• Node.js 20+ with Temporal TypeScript SDK.
• Fast.io API key (create via dashboard or POST /user/auth/key).
• Public webhook URL (ngrok for local, Vercel for prod).

Install SDKs:

npm init -y
npm i @temporalio/client @temporalio/worker @temporalio/workflow @temporalio/activity @temporalio/activity-core @temporalio/common typescript tsx express

Set env vars:

FASTIO_API_KEY=your_key
TEMPORAL_HOST=localhost:7233
WEBHOOK_SECRET=your_secret

Test Fast.io API access with curl.

Webhooks configure per workspace via API. First, create or list workspaces.

List workspaces:

curl -H "Authorization: Bearer $FASTIO_API_KEY" https://api.fast.io/current/workspaces/

Create webhook (assume endpoint POST /workspaces/{workspaceId}/webhooks/):

curl -X POST -H "Authorization: Bearer $FASTIO_API_KEY" \
  -d "url=https://your-domain.com/webhook" \
  -d "events=upload,modify,access" \
  -d "secret=your_secret" \
  https://api.fast.io/current/workspaces/{workspaceId}/webhooks/

Note: Exact endpoint in Fast.io Events docs. Payloads include eventId for dedup.

Test by uploading a file via dashboard. Check your logs for POST.

Create webhook.ts with Express.

import express from 'express';
import { WorkflowClient } from '@temporalio/client';
import crypto from 'crypto';

const app = express();
app.use(express.json({ verify: verifySignature }));

function verifySignature(req: express.Request, res: express.Response, buf: Buffer) {
  const signature = req.headers['fastio-signature'] as string;
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.WEBHOOK_SECRET!).digest('hex');
  if (signature !== expected) throw new Error('Invalid signature');
}

const client = new WorkflowClient();

app.post('/webhook', async (req, res) => {
  const event = req.body;
  if (event.eventType !== 'upload') return res.sendStatus(200);

const workflowId = `file-process-${event.eventId}`;
  await client.execute('FileProcessingWorkflow', {
    taskQueue: 'file-queue',
    workflowId,
    args: [event],
  });
  res.json({ received: true });
});

app.listen(3000);

Deploy to Vercel or Railway.

Workflows are deterministic functions. Define workflows.ts:

import { proxyActivities, defineWorkflow } from '@temporalio/workflow';

const activities = proxyActivities({
  startToCloseTimeout: '1 day',
  retry: { maximumAttempts: 5 },
});

export async function FileProcessingWorkflow(event: any): Promise<string> {
  const resultId = await activities.downloadAndProcess(event.fileId, event.workspaceId);
  await activities.notifyCompletion(resultId);
  return resultId;
}

Activities in activities.ts:

import { Context } from '@temporalio/activity';

export async function downloadAndProcess(fileId: string, workspaceId: string): Promise<string> {
  // Download via Fast.io API
  const response = await fetch(`https://api.fast.io/current/workspaces/${workspaceId}/storage/${fileId}/download/`, {
    headers: { Authorization: `Bearer ${process.env.FASTIO_API_KEY}` },
  });
  const buffer = Buffer.from(await response.arrayBuffer());
  // Process e.g. resize image or transcode video
  const processed = await someProcessing(buffer);
  // Upload back
  const uploadId = await uploadProcessed(processed, workspaceId);
  return uploadId;
}

Implement someProcessing and uploadProcessed as your logic.

Worker connects workflow to task queue.

import { Worker } from '@temporalio/worker';

const worker = await Worker.create({
  workflowsPath: './workflows',
  activities: { downloadAndProcess, notifyCompletion },
  taskQueue: 'file-queue',
});
await worker.run();

Run with tsx worker.ts.

Scale by multiple workers.

1. Start Temporal UI: http://localhost:8080
2. Start worker.
3. Configure webhook.
4. Upload file to workspace.
5. Watch webhook hit, workflow start in UI.
6. Verify processed file appears.

Use ngrok for local webhook: ngrok http 3000

Idempotency: Use eventId as workflow ID. Check if running before start.

Retries: Temporal retries activities. Make activities idempotent (e.g. check if processed).

Large Files: Chunk downloads if API supports. Temporal handles long activities.

Timeouts: Set per-activity timeouts.

Security: Always verify signatures. Use HTTPS.

Monitoring: Query Temporal visibility for metrics.

Troubleshoot: Check Fast.io audit logs, Temporal history.