Description

Receive incoming emails via JSON webhooks and wake the agent. Built for AI Commander.

README (SKILL.md)

Email Webhook Receiver

Name: Email Webhook
Author: lksrz

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 `\x3Cpath-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 \x3Csecret> header.

Data Storage

Local Inbox: Incoming emails (raw body and metadata) are appended to a local inbox.jsonl file.
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 [email protected]
```

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 PORT env 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.

Usage Guidance

This skill appears to implement an email webhook server, but there are several mismatches you should review before installing: - Environment variables: the code requires OPENCLAW_AGENT_ID (and optionally OPENCLAW_GATEWAY_TOKEN) but only WEBHOOK_SECRET is declared in the registry. Confirm you are comfortable providing an agent ID and, if used, a gateway token (sensitive) to this process. - Binaries: the script calls `openssl` to generate a self-signed cert. Ensure openssl is available on the host or the startup will fail; the registry didn't list openssl as required. - Wake behavior mismatch: SKILL.md says it triggers `openclaw system event`, but the code runs `openclaw agent ... --message ... --deliver`. Verify that this wake mechanism aligns with your expectations and permissions for the agent CLI. - Network behavior: on startup the server calls an external IP service (api.ipify.org) and attempts to reach back to its public IP:port. This leaks the host's public IP to a third party and probes your port; review whether you accept that behavior. - Data storage & exposure: incoming emails (raw body and metadata) are appended to a local inbox.jsonl file and a self-signed certificate is stored under ../ssl. Ensure the host filesystem and backups are acceptable places for potentially sensitive email content and that firewall/Cloudflare setup is configured safely. Recommendation: if you plan to install, (1) request the skill author to update the registry metadata to declare OPENCLAW_AGENT_ID and optional OPENCLAW_GATEWAY_TOKEN and to list openssl as a required binary, (2) audit the openclaw CLI invocation and confirm the gateway token scope, (3) run the server in a restricted environment (dedicated host or container), set a strong WEBHOOK_SECRET, and ensure firewall/Cloudflare settings restrict exposure. If you cannot verify those items, treat the skill as suspicious and do not deploy it on a sensitive/shared host.

Capability Analysis

Type: OpenClaw Skill Name: email-webhook Version: 2.6.0 The OpenClaw AgentSkills skill bundle for 'email-webhook' is classified as benign. The `scripts/webhook_server.js` implements robust security measures, including `child_process.spawn` with argument arrays to prevent command injection when calling the `openclaw` CLI, and `path.basename()` to sanitize the `INBOX_FILE` path, preventing path traversal. The `SKILL.md` instructions for the AI agent are directly related to processing incoming emails and do not contain any prompt injection attempts to manipulate the agent for malicious purposes. All network calls and file operations are aligned with the stated purpose of receiving and logging emails, and waking the agent.

Capability Assessment

⚠ Purpose & Capability

The skill's stated purpose (receive emails via JSON webhooks and wake an agent) matches the code's functionality, but the declared registry metadata is incomplete: the runtime actually requires OPENCLAW_AGENT_ID (the server exits if it's missing) and optionally reads OPENCLAW_GATEWAY_TOKEN, yet the registry only lists WEBHOOK_SECRET. The code also invokes the openclaw CLI (expected) and calls openssl to generate a self-signed certificate (openssl is not declared as a required binary). These undeclared requirements are disproportionate to what the registry claims.

⚠ Instruction Scope

SKILL.md and the runtime disagree in several places: SKILL.md says the server fires `openclaw system event --mode now`, but the code actually spawns `openclaw agent --agent ... --message ... --deliver`. SKILL.md documents CLOUD/PORT values inconsistently (mentions 2082 then 2083). The runtime writes full email bodies and metadata to a local inbox.jsonl, generates/writes SSL cert files under ../ssl, and performs outgoing network checks (calls api.ipify.org and attempts to fetch its own public IP:port). SKILL.md does not fully document the external network calls or the optional OPENCLAW_GATEWAY_TOKEN usage. While most actions align with the stated purpose, these undocumented/contradictory instructions are scope creep and merit attention.

✓ Install Mechanism

The install spec only adds an npm dependency ([email protected]), which is proportional and expected. There are no downloads from arbitrary URLs or extract operations. However, the runtime uses the system openssl binary via execSync to create certificates; openssl is not in the install or required-binaries list, so the environment may fail at runtime unless openssl is present.

⚠ Credentials

WEBHOOK_SECRET is a reasonable primary credential. However, the code requires OPENCLAW_AGENT_ID (exit if missing) but this is not declared in the registry metadata; that's a notable mismatch. The code also optionally reads OPENCLAW_GATEWAY_TOKEN and will pass it to the openclaw CLI if present — this is a potentially sensitive token that is not documented in the registry. The number and sensitivity of environment variables (gateway token, agent ID) is higher than the registry declares and should be justified.

ℹ Persistence & Privilege

The skill does not request always:true and does not modify other skills. It writes local files (inbox.jsonl and generated SSL files in ../ssl) and spawns the openclaw CLI to notify the agent. Writing its own inbox and certs is expected for a webhook server, but you should be aware it will create files under the server working directory and attempt to open a public port, which has operational and privacy implications.

Version History

v2.6.0

OPENCLAW_AGENT_ID now required (like WEBHOOK_SECRET). Skill belongs to the agent — always targets only that agent. Removed system event fallback entirely.

v2.5.0

Critical fix: added OPENCLAW_AGENT_ID env var. Without it, system event woke ALL agents on server. Now uses 'openclaw agent --agent ID' to target only the owning agent. Warns loudly if not set.

v2.4.0

Added Agent Setup section to SKILL.md: post-install instructions telling the agent to add inbox.jsonl polling to HEARTBEAT.md and notify user via last active channel

v2.3.0

Works with Cloudflare Flexible SSL + self-signed cert on port 2083. No need to switch to Full SSL.

v2.2.0

HTTPS with auto-generated self-signed cert (valid 10y). Uses port 2083. Requires Cloudflare SSL mode: Full. Cert generated on first run via openssl.

v2.1.0

Self-check on startup: server detects public IP and verifies port is reachable from internet. Clear OK/FAIL messages with fix instructions if port is blocked.

v2.0.0

Default port changed to 2083 (Cloudflare-supported HTTPS port). PORT env var configurable. Updated SKILL.md with correct CF setup instructions.

v1.9.0

Fixed: OPENCLAW_WEBHOOK_URL must use http:// not https:// — CF supports port 2082 for HTTP origins only. Flexible SSL handles HTTPS at the CF edge.

v1.8.0

Fixed docs: no nginx needed. Cloudflare supports port 2082 natively — just include :2082 in OPENCLAW_WEBHOOK_URL. Startup message now shows correct URL format.

v1.7.0

Added reverse proxy warning on startup + SKILL.md infrastructure section explaining nginx requirement for Cloudflare Flexible SSL setups

v1.6.0

Better startup error: missing WEBHOOK_SECRET now prints a clear configuration guide with example Cloudflare Worker code instead of a cryptic error message

v1.5.3

- Updated SKILL.md with detailed metadata for installation and runtime dependencies. - Changed the agent wake command to use openclaw system event --mode now. - Added documentation on environment variables and their defaults. - Provided explicit setup instructions for installing and starting the server. - Removed deprecated _meta.json file.

v1.5.2

Fix: Corrected the 'wake' command to use 'openclaw system event --mode now'.

v1.5.1

Metadata Fix: Re-added _meta.json and simplified SKILL.md frontmatter to ensure registry correctly displays environment variables and install steps.

v1.5.0

Security Patch: Fixed command injection vulnerability in wake mechanism by switching from child_process.exec to spawn. Improved metadata consistency.

v1.4.0

Feature: Added 'Wake' mechanism to alert the agent on new emails. Metadata: Standardized YAML frontmatter for better registry compatibility. Security: Removed separate _meta.json to prevent conflicts.

v1.3.1

Security & Privacy: Added explicit warnings about data storage, sensitive content, and mandatory authentication. Improved registry metadata clarity.

v1.3.0

Security & Metadata Fix: Added _meta.json to explicitly declare environment variables and install steps for the registry.

v1.2.1

Branding: Reverted name to 'Email Webhook Receiver' as per Lucas's request while keeping the generic implementation improvements.

v1.2.0

General release: Made the skill agnostic to the mail source. Added JSON schema documentation and a Cloudflare Worker example code in SKILL.md.

Metadata

Slug email-webhook

Version 2.6.0

License —

All-time Installs 5

Active Installs 5

Total Versions 22

Frequently Asked Questions

What is Email Webhook?

Receive incoming emails via JSON webhooks and wake the agent. Built for AI Commander. It is an AI Agent Skill for Claude Code / OpenClaw, with 1006 downloads so far.

How do I install Email Webhook?

Run "/install email-webhook" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Email Webhook free?

Yes, Email Webhook is completely free (open-source). You can download, install and use it at no cost.

Which platforms does Email Webhook support?

Email Webhook is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Email Webhook?

It is built and maintained by Coder AI (@lksrz); the current version is v2.6.0.

More Skills

Email Webhook