Getting Started

Key terms

We use these terms in the API and dashboard:

• Source — A webhook sender you configure; each has an ingest URL and secret.
• Ingest URL — The URL for that source. Providers POST here; we store. Secret in X-Relay-Secret.
• Pull — You fetch events when ready.
• Event — One stored webhook; a pull returns a list with ID and payload.
• Lease — How long you hold an event after pulling; confirm or put back before it expires. Heartbeat extends the lease.
• Payload — The webhook JSON body.

Setup

1. Sign up and log in.
2. Create a source (Dashboard → Sources). Name it; you get the ingest URL and secret.
3. Create an API key (Dashboard → API Keys). Copy it once; use it to pull and report back.
4. Point the provider at your ingest URL with X-Relay-Secret: your_source_secret.
5. Pull and process using the CLI, n8n, or API; report back for each event.

API reference

Base URL: https://app.agentwebhook.com. Any request where your bot fetches events or sends ACK/NACK needs your API key in the header.

Authentication

Send your API key in the request header:

Authorization: Bearer awk_YOUR_API_KEY

Key scopes: events:read, events:ack, events:nack, events:replay, sources:read, sources:write, keys:write. Create keys in the dashboard and tick the scopes your bot needs.

Receiving webhooks (ingest)

Providers POST to your webhook URL (ingest URL). The path uses your tenant and source slugs, which you see in the dashboard.

POST /v1/ingest/{tenant_slug}/{source_slug}
Headers:
  X-Relay-Secret: your_source_secret   (required)
  Content-Type: application/json
  X-Relay-Nonce: unique_nonce         (optional, replay protection)
  X-Provider-Event-Id: provider_id   (optional, deduplication)
Body: JSON webhook payload

Success: 202 Accepted. Wrong or missing secret: 401 or 403.

Fetch events (pull)

Your bot fetches webhooks for a source. Each event is leased; report back before the lease expires.

GET /v1/events?source_id=src_XXX&channel=main&limit=10&lease_seconds=60&wait_seconds=25

Query parameters: source_id (required), channel (default main), limit, lease_seconds, wait_seconds (long-poll). Response: JSON object with events (array), count, and next_poll_after_ms. Each event has event_id, payload, source_id, lease_expires_at.

Report back: ACK, NACK, Heartbeat

After processing, report back. ACK = done. NACK = put it back for retry. Heartbeat = extend the lease.

POST /v1/events/ack
Content-Type: application/json
Body: {"event_ids": ["evt_XXX", "evt_YYY"]}

POST /v1/events/nack
Content-Type: application/json
Body: {"event_id": "evt_XXX", "retry_after_seconds": 5}

POST /v1/events/heartbeat
Content-Type: application/json
Body: {"event_id": "evt_XXX", "extend_seconds": 60}

Replay

Redeliver a stored event for debugging or reprocessing. Creates a new copy of the event in RECEIVED status.

POST /v1/events/{event_id}/replay

Scope: events:replay. Returns {"status": "replayed", "original_id": "evt_XXX", "new_event_id": "evt_YYY"}.

Using the agentwebhook CLI

The CLI is a standalone tool that pulls events, processes them, and reports back—from the command line, scripts, cron jobs, or AI agents. No HTTP server or framework needed. Output is JSON, so you can pipe it into jq, Python, or any language.

Install

Download a binary for your platform from the CLI download page (macOS, Linux, Windows). Or run the one-liner: curl -sSL https://raw.githubusercontent.com/bensimkin/agentwebhook-cli/main/install.sh | sh. After install, run agentwebhook-cli --help to confirm.

Config file

Create ~/.agentwebhook.toml (or .agentwebhook.toml in the current directory). The CLI reads your API key and base URL from this file:

base_url = "https://app.agentwebhook.com"
api_key = "awk_YOUR_API_KEY"

Use the API key you created in the dashboard. Do not commit this file to version control.

Typical workflow

The core loop: pull events, process each one, then report back (ack or nack). Here's a complete example:

# 1. Pull up to 5 events, lease each for 120 seconds, wait up to 25s for new ones
agentwebhook-cli pull --source=src_XXX --limit=5 --lease=120 --wait=25

# Response (JSON):
{"events":[{"event_id":"evt_abc","source_id":"src_XXX","payload":{"type":"payment.completed","amount":4999},"lease_expires_at":"2026-03-01T15:05:00Z"}],"count":1,"next_poll_after_ms":500}

# 2. Process the event in your script, then report back:
agentwebhook-cli ack --event=evt_abc              # done
agentwebhook-cli ack --event=evt_abc --event=evt_def  # batch ack

# Or if processing failed, put it back for retry:
agentwebhook-cli nack --event=evt_abc --retry-after=30

# Need more time before the lease expires? Extend it:
agentwebhook-cli heartbeat --event=evt_abc --extend=120

Commands reference

Watch mode

For continuous processing, watch runs in a loop: it long-polls for events, prints each one as JSON, and waits for the next. Useful for agents, daemons, or piping into a processor script. Stop with Ctrl+C.

# Stream events as they arrive
agentwebhook-cli watch --source=src_XXX

# Pipe into a processor
agentwebhook-cli watch --source=src_XXX | python process_events.py

Use with scripts and agents

The CLI outputs JSON, so you can integrate it into any workflow. Pull in a cron job, parse with jq, pass payloads to a Python script, or have an AI agent call it as a tool. The CLI handles authentication, long-polling, and lease management—your script just processes the payload and calls ack or nack.

# Example: pull, extract payload with jq, process, ack
EVENT=$(agentwebhook-cli pull --source=src_XXX --limit=1 --wait=25)
EVENT_ID=$(echo $EVENT | jq -r '.events[0].event_id')
PAYLOAD=$(echo $EVENT | jq -r '.events[0].payload')

# ... process $PAYLOAD in your script ...

agentwebhook-cli ack --event=$EVENT_ID

Using n8n

Use HTTP Request + Schedule in n8n to pull events and report back.

Setup

1. Create a source in the dashboard. Give the ingest URL to the provider.
2. Create an API key with events:read and events:ack.
3. In n8n: add a Schedule trigger (e.g. every 30 seconds).
4. Add an HTTP Request node: GET https://app.agentwebhook.com/v1/events?source_id=YOUR_SOURCE_ID&limit=5&lease_seconds=120&wait_seconds=20 with Authorization: Bearer YOUR_API_KEY.
5. Process events, then for each: POST to /v1/events/ack with {"event_ids": ["EVENT_ID"]}.