Email Webhook Receiver
This skill provides a secure endpoint to receive emails as standardized JSON webhooks and automatically wakes the agent.
🤖 Agent Setup (Post-Install)
After installing and starting this skill, add the following logic to your HEARTBEAT.md:
### 📧 Inbound Email Check
- Read `<path-to-inbox.jsonl>` (configured via INBOX_FILE or default: inbox.jsonl in cwd)
- Compare the latest `receivedAt` timestamp with your last-checked timestamp
- If there are NEW emails since last check:
- Notify the user via their last active communication channel (Discord, WhatsApp, etc.)
- Format: "📧 New email from [from]: [subject] — [text preview]"
- Update your last-checked timestamp
- If no new emails: continue silently
💡 You don't need to know the user's channel in advance — use the most recently active channel from your session history. If you're unsure how to reach the user, ask them directly.
The skill fires openclaw system event on each incoming email to wake you immediately. Your HEARTBEAT.md logic will then run and handle the notification.
⚡️ Wake Mechanism
When an email is received, the server invokes openclaw system event --mode now. This ensures the agent is notified immediately and can process the incoming communication without waiting for the next heartbeat cycle.
🚨 Security & Privacy
Command Injection Protection
The server uses secure process spawning (child_process.spawn) with argument arrays instead of shell execution. User-controlled input (email headers) cannot be used to execute arbitrary system commands.
Path Traversal Protection
The INBOX_FILE parameter is sanitized using path.basename(), ensuring that files are only written within the server's working directory.
Authentication
A strong WEBHOOK_SECRET environment variable is REQUIRED for the server to start. All incoming requests must provide this secret in the Authorization: Bearer <secret> header.
Data Storage
- Local Inbox: Incoming emails (raw body and metadata) are appended to a local
inbox.jsonlfile. - Cleanup: Users should periodically rotate or delete the inbox file to save disk space and protect privacy.
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
WEBHOOK_SECRET | Yes | — | Secret token for webhook authentication. |
OPENCLAW_AGENT_ID | Yes | — | Your agent ID (e.g. skippy). Without this, incoming emails wake ALL agents on the server. |
PORT | No | 2083 | Port to listen on. Configurable — set to match your OPENCLAW_WEBHOOK_URL. |
INBOX_FILE | No | inbox.jsonl | Filename for the activity feed. |
Setup
- Install dependencies:
npm install express@4.21.2 - Start Server:
WEBHOOK_SECRET=your-strong-token node scripts/webhook_server.js
Cloudflare Setup
This server listens on port 2082. Cloudflare natively supports port 2082 as an HTTP origin port with Flexible SSL.
When configuring your Cloudflare Email Worker, set OPENCLAW_WEBHOOK_URL using http:// with the port explicitly:
https://webhook.yourdomain.com:2083/api/email
Port 2083 is a Cloudflare-supported port. Works with Flexible SSL — the server uses a self-signed certificate (auto-generated on first run) which Cloudflare accepts on this port.
⚠️ If you use a different port, set the
PORTenv var when starting the server. ⚠️ If you omit the port in the Worker URL, Cloudflare defaults to port 80 → 404.
DNS setup: create an A record for webhook.yourdomain.com pointing to your server IP with the orange cloud (proxy) enabled.
Runtime Requirements
Requires: express, node, openclaw CLI.