# How to Set Up Webhook Notifications in OpenClaw

OpenClaw webhook notifications help agents handle Fastio workspace events right away. By connecting an event listener to Fastio's WebSocket events feed or polling the activity feed, you can trigger HTTP webhooks to your agent on file uploads, edits, access, and agent handoffs. This guide walks you through setup, from connection to testing.

Source: https://fast.io/resources/openclaw-webhook-notifications/
Last reviewed: 2026-02-17

## What Are OpenClaw Webhook Notifications?

OpenClaw webhook notifications deliver real-time triggers to your agent endpoint when workspace events occur. Fastio provides a WebSocket events feed and a realtime activity feed that an event bridge can use to dispatch HTTP POST webhooks to OpenClaw 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.

Event streaming provides instant notification compared to long polling intervals. Fastio streams events over a WebSocket connection or exposes them in the realtime activity feed. Your agents stay in sync with workspace activity.

Events arrive fast and reliably. The append-only audit log records every action, and developers rely on real-time event feeds for building production-grade reactive agents without worrying about missed events.

## Prerequisites

Install [OpenClaw](https://openclaw.ai). Set up a public HTTPS endpoint for POST requests. Use ngrok for testing: `ngrok http 5000`.

Sign up for a Fastio account at [/storage-for-agents/](/storage-for-agents/) using the 14-day Business Trial (credit card required; see [pricing](/pricing/)).

Connect your OpenClaw agent to the remote Fastio MCP server at https://mcp.fast.io/mcp using your scoped API key from Settings > API Keys. With these prerequisites met, you can securely connect OpenClaw agents to Fastio workspace events.

## Configuration Steps

Follow these steps to listen for events and trigger webhooks.

**Step 1: Create a Workspace**

Create a workspace named 'webhook-test' using the web UI or REST API:

```
POST https://api.fast.io/current/workspaces
```

Note the workspace ID from the response, like `ws_1234567890123456789`.

**Step 2: Build Your Endpoint**

Python Flask example:

```python
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('X-Bridge-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:

```javascript
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['x-bridge-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: Connect to the Events Feed**

Subscribe to Fastio's WebSocket events feed or poll the activity feed via the REST API at https://api.fast.io/current/ to forward events to your webhook endpoint:

```bash
curl -H "Authorization: Bearer {api_key}" \
  "https://api.fast.io/current/workspaces/{workspace_id}/activity"
```

Replace `{workspace_id}` and `{api_key}`.

**Step 4: Verify Event Delivery**

Confirm your bridge receives activity events and dispatches HTTP POST payloads to your OpenClaw webhook handler.

## Webhook Payload Format

Payloads are JSON POST bodies. Example file upload:

```json
{
  "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:

| Event | Description |
|-------|-------------|
| `file.uploaded` | New file added |
| `file.modified` | File updated or renamed |
| `file.accessed` | File viewed or downloaded |
| `agent.handoff` | Ownership transfer completed |
| `workspace.member_added` | New member joined |
| `workspace.member_removed` | Member left |
| `share.created` | New share made |
| `comment.added` | New comment posted |

Handle by event type:

```python
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'])
```

## Testing Webhooks

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.

Check the activity feed and audit logs in your workspace for delivery verification and event history.

## Real-World Use Cases

**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 Fastio'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 events to OpenClaw agents via the remote Fastio MCP server.

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

Uses the consolidated MCP toolset to respond intelligently.

## Security Best Practices

Use HTTPS endpoints only. Verify signatures with shared secret.

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

Rate limit your endpoint and handle event payloads asynchronously.

Log payloads without sensitive data. Use workspace_id/file_id.

Rotate secrets periodically across your bridge and webhook receivers. 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.

## Troubleshooting

**No events?** Check your WebSocket connection or activity polling script. Test endpoint access with curl. Confirm subscribed events match.

**Delivery failed?** Check your receiver 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 your bridge listener configuration.

Activity endpoint: GET https://api.fast.io/current/workspaces/{id}/activity. If problems continue, share specific error logs with Fastio support for assistance.

## Frequently asked questions

### How do I configure OpenClaw event webhooks?

Set up an HTTPS endpoint, connect an event listener to Fastio's WebSocket events feed or activity feed, and forward events to your agent.

### What events trigger webhooks?

file.uploaded, file.modified, file.accessed, agent.handoff, workspace.member_added/removed, share.created.

### Are Fastio event streams reliable?

Yes. Events use durable real-time streams and an append-only audit log.

### How to secure webhooks?

HTTPS, signature verification with secret, quick 200 responses, async processing.

### Webhook payload size?

Small JSON payloads include IDs, names, timestamps, and metadata.

### Can an event bridge trigger multiple webhook endpoints?

Yes, your bridge can inspect workspace events and dispatch notifications to multiple webhook endpoints or agents based on event type.

### Does Fastio have native outbound webhooks?

Fastio provides a WebSocket events feed and an activity polling feed. A lightweight bridge receives these events and dispatches HTTP POST webhooks to your agents.

### Rate limits on event notifications?

The WebSocket events feed and activity feed stream events in real time as actions occur in the workspace.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.