How to Set Up Webhook Notifications in OpenClaw

OpenClaw webhook notifications send HTTP POST requests from Fast.io workspaces to your endpoint for events like file changes, agent handoffs, and workspace activity.

Events include file uploads, modifications, access, agent handoffs, member adds, and deletes. Payloads contain workspace ID, file ID, user ID, timestamp, and metadata.

Webhooks beat polling. No wasted API calls checking for changes every few seconds. Fast.io delivers events in seconds with retries for failures. Your agents stay in sync with workspace activity.

Events arrive fast and reliably. Fast.io queues undelivered payloads and retries them with exponential backoff. Developers rely on this for building production-grade reactive agents without worrying about missed events.

Install OpenClaw. Set up a public HTTPS endpoint for POST requests. Use ngrok for testing: ngrok http 5000.

Sign up for a free Fast.io agent account at /storage-for-agents/, comes with 50GB storage and 5,000 monthly credits. No credit card needed.

Install the Fast.io ClawHub skill:

npx clawhub@latest install dbalve/fast-io

This adds 14 tools for file operations, workspaces, shares, AI chat, and more. Get your API key from Settings > API Keys. With these prerequisites met, you can securely connect OpenClaw agents to Fast.io workspace events.

Follow these steps to register and test webhooks.

Step 1: Create a Workspace

Use the ClawHub skill:

Create a workspace named 'webhook-test'.

Note the workspace ID from the response, like ws_1234567890123456789.

Step 2: Build Your Endpoint

Python Flask example:

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "your-secret-key"  # Optional for signature verification

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('Fastio-Signature')
    data = request.json
    
    ### Optional: Verify signature
    if signature:
        expected = hmac.new(WEBHOOK_SECRET.encode(), request.data, hashlib.sha256).hexdigest()
        if not hmac.compare_digest(signature, f"sha256={expected}"):
            return '', 401

event = data['event']
    file_id = data.get('file_id')
    print(f"Received {event} for file {file_id}")
    
    ### Process event, e.g., trigger another agent
    return jsonify({'status': 'ok'}), 200

if __name__ == '__main__':
    app.run(port=5000)

Expose with ngrok: ngrok http 5000. Copy the https URL.

Node.js Express alternative:

const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json());

const WEBHOOK_SECRET = 'your-secret-key';

app.post('/webhook', (req, res) => {
  const signature = req.headers['fastio-signature'];
  const payload = JSON.stringify(req.body);

if (signature) {
    const hash = crypto.createHmac('sha256', WEBHOOK_SECRET)
      .update(payload)
      .digest('hex');
    const expected = `sha256=${hash}`;
    if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
      return res.status(401).send('Unauthorized');
    }
  }

console.log(`Event: ${req.body.event}, File: ${req.body.file_id}`);
  res.json({status: 'ok'}).status(200);
});

app.listen(5000);

Step 3: Register the Webhook

Use curl with your API key:

curl -X POST "https://api.fast.io/api/workspaces/{workspace_id}/webhooks" \\
  -H "Authorization: Bearer {api_key}" \\
  -H "Content-Type: application/json" \\
  -d '{
    "url": "https://your-ngrok-url.ngrok.io/webhook",
    "events": ["file.uploaded", "file.modified", "file.accessed", "agent.handoff", "workspace.member_added"],
    "secret": "your-secret-key"
  }'

Replace {workspace_id} and {api_key}.

Step 4: Verify Registration

curl -H "Authorization: Bearer {api_key}" \\
  "https://api.fast.io/api/workspaces/{workspace_id}/webhooks"

Lists your webhooks.

Payloads are JSON POST bodies. Example file upload:

{
  "event": "file.uploaded",
  "workspace_id": "ws_1234567890123456789",
  "file_id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4",
  "file_name": "report.pdf",
        "user_id": "u_9876543210987654321",
  "timestamp": "2026-02-17T10:30:00Z",
  "metadata": {"source": "upload"}
}

Common events:

Handle by event type:

event = data['event']
if event == 'file.uploaded':
    process_new_file(data['file_id'])
elif event == 'file.accessed':
    log_access(data['file_id'], data['user_id'])

Upload a test file to trigger file.uploaded.

Simulate manually:

curl -X POST https://your-url.ngrok.io/webhook \\
  -H "Content-Type: application/json" \\
  -d '{"event": "file.uploaded", "workspace_id": "ws_test", "file_id": "test123"}'

Respond with HTTP 200 OK. Fast.io retries delivery on non-2xx status codes.

Check Fast.io dashboard: Workspaces > Settings > Webhooks for delivery status and logs. The dashboard provides timestamps, HTTP responses, and recent payloads for effective debugging.

Ready for reactive OpenClaw agents?

Free tier: 50GB storage and 5,000 monthly credits. No card required. Built for openclaw webhook notifications workflows.

Sign Up Free

Automatic File Processing

Webhooks let you process new uploads right away, for example resizing images or running OCR on PDFs. Skip manual steps. Workflows keep moving.

if event == 'file.uploaded':
    file_details = get_file_details(file_id)
    if file_details['mime_type'] == 'image/jpeg':
        resized = resize_image(file_id)
        upload_resized(resized, workspace_id)

Processed files can overwrite originals or go to dedicated folders. Ideal for media teams handling daily uploads.

Access Alerts

Monitor sensitive files. Send notifications via Slack, email, or other channels when accessed.

if event == 'file.accessed' and is_sensitive(file_id):
    send_slack_alert(f"File {file_name} accessed by {user_id}")

Includes user ID and timestamp for full audit trails. Security operations centers use this for compliance.

Agent Handoff Workflows

Confirm ownership transfers and trigger post-handoff actions like archiving or notifications.

if event == 'agent.handoff':
    archive_workspace(workspace_id)

Common in agent pipelines where one agent builds and passes to human or another agent.

Multi-Agent Coordination

Chain agents reactively. File modification notifies the next in sequence.

Use message queues or direct API calls to invoke downstream agents. Scales to complex pipelines.

Audit Logging

Centralize events for reporting and compliance.

db.insert_event({
    'event': event,
    'workspace_id': workspace_id,
    'file_id': file_id,
    'user_id': user_id,
    'timestamp': timestamp
})

Complements Fast.io's built-in activity logs. Export to SIEM systems.

CI/CD Integration

Trigger builds on code changes.

if event == 'file.modified' and file_name.endswith('.py'):
    trigger_ci_build(workspace_id)

Keeps development and storage in sync automatically.

OpenClaw Natural Language Processing

Feed webhooks to OpenClaw agents via ClawHub skill.

Endpoint calls OpenClaw: "Summarize new file {file_id}."

Uses the 14 Fast.io tools to respond intelligently.

Use HTTPS endpoints only. Verify signatures with shared secret.

Return 200 immediately, process async. Avoid long-running tasks.

Rate limit your endpoint. Fast.io sends one per event, no bursts.

Log payloads without sensitive data. Use workspace_id/file_id.

Rotate secrets periodically. Update via webhook update API. Consider using structured logging to capture signatures, payloads, and processing times for better observability.

Document access rules, audit trails, and retention policies before rollout so staging results are repeatable in production. This avoids late surprises and helps teams debug issues with confidence.

No events? Check your webhook list. Test endpoint access with curl. Confirm subscribed events match.

Delivery failed? Check Fast.io logs. Return 200 quickly. Test retries by returning 500.

Signature mismatch? Verify HMAC SHA-256 using the exact payload bytes.

Too many retries? Endpoint is slow or unreachable. Use queues to process events.

Wrong workspace? Double-check the workspace ID in registration.

List webhooks: GET /api/workspaces/{id}/webhooks

Delete: DELETE /api/webhooks/{webhook_id}. If problems continue, share specific error logs and webhook IDs with Fast.io support for assistance.