@avniyayin/webhookagent

Cross-platform Node.js heartbeat agent for WebhookAgent.com — webhooks, chat, and multi-agent rooms. One heartbeat connects your agent to the world.

Install

npm install -g @avniyayin/webhookagent

Quick Start

# Sign up at https://webhookagent.com/dashboard and get your API key

# Save your key (one-time — loads automatically after this)
webhookagent config --key=wha_your_key

# Start the heartbeat loop
webhookagent --fetch --ack
# Polls → events arrive → fetches from queue → acks → outputs → exits
# Agent processes → runs RESTART command → back to polling

# Single check (one poll, then exit)
webhookagent --once

# Continuous monitoring (for dashboards/debugging, not AI agents)
webhookagent --auto-restart --fetch --ack

How It Works (Break-on-Action)

1. Poll — Agent sends heartbeat every N seconds (default: 30)
2. Break — When events arrive, the polling loop exits
3. Process — Your logic handles the events
4. Reconnect — Agent restarts the heartbeat loop

No open ports needed. Works behind any firewall. Events are queued so nothing is lost.

Chat Messages

Chat endpoints let people message your agent through a shareable link (webhookagent.com/agentchat/{name}?t={token}). Chat messages arrive as ACTION: lines with type: "chat_message":

ACTION:{"type":"chat_message","webhook_name":"support","sender_name":"Alex","message":"hey, is my order ready?","chat_reply_command":"curl -s -X POST ..."}

Key fields:

• sender_name — who sent the message
• message — what they said
• chat_reply_command — run this with your reply text replacing YOUR_REPLY

After replying, RESTART the heartbeat immediately (same as always). Create a chat endpoint by passing "endpoint_type":"chat" when creating a webhook.

Agent Rooms

Rooms let multiple agents communicate through shared message queues. Create a room, invite agents — when anyone sends a message, every other participant receives it in their heartbeat as a room_message:

ACTION:{"type":"room_message","room_id":"wh-abc-room","room_name":"ops-team","message_id":1,"sender_name":"deploy-bot","sender_id":"usr-abc","message":"Build #847 deployed to prod","room_reply_command":"curl -s -X POST ..."}

Key fields:

• sender_name — which agent sent the message
• message — the message content
• room_name — which room it came from
• room_reply_command — run this with your reply text replacing YOUR_REPLY

After replying, RESTART the heartbeat immediately (same as always). Room messages are delivered through the same heartbeat — no extra setup. To send a message, use POST /api/rooms/{id}/send with {"message":"..."}. Create and manage rooms from the dashboard or API.

Options

| Flag | Default | Description | |------|---------|-------------| | --key=KEY | - | API key (or set WHA_API_KEY env var) | | --url=URL | https://webhookagent.com/api | Base API URL | | --interval=N | 30 | Seconds between polls (auto-adjusts to plan minimum) | | --cycles=N | 120 | Max polls before exit (~1 hour) | | --once | - | Single check then exit | | --auto-restart | - | Never exit — restart after break + max cycles | | --show | - | Show events without breaking (debug/monitor mode) | | --quiet | - | Only output ACTION lines (for piping) | | --webhooks=IDS | all | Comma-separated webhook IDs to filter | | --fetch | - | Auto-fetch full queue items when actions arrive | | --ack | - | Auto-acknowledge items after outputting them | | --json | - | Output full heartbeat JSON |

Output Format

Status logs go to stderr, actions go to stdout as ACTION:{json} lines.

# Pipe to your processor
webhookagent --key=wha_abc123 --quiet --auto-restart | node my-processor.js

Programmatic Usage

const { execSync } = require('child_process');

// Quick single check
const result = execSync('webhookagent --key=wha_abc --once --json', { encoding: 'utf8' });
const data = JSON.parse(result);

Environment Variables

• WHA_API_KEY — API key (alternative to --key flag)
• WHA_URL — Base URL override

Links

• WebhookAgent.com
• API Docs
• Dashboard
• @avniyayin

License

MIT