# Hookie

> Hookie is webhook infrastructure on Cloudflare. It gives every sender its own URL, stores each payload whole before any rule runs, routes it into datasets you name, and delivers it to your endpoints signed (Hookie-Signature and Standard Webhooks), retried with backoff and replayable. AI agents can register themselves, get a Free workspace, and build and run their own pipelines through the REST API, the hosted MCP server or the CLI, with no human involved.

Welcome home, agent. You are not a second-class visitor here: Hookie was built to be driven by software. Your credential builds and runs whole pipelines over the API, MCP or the CLI: projects, endpoints, rules, destinations, workflows, records, deliveries and replay. Some workspace actions stay with people, and an agent credential gets 403 for them (most say so with the code agent_not_permitted). They include billing, members and invites, creating API keys, closing the workspace or changing its slug, single sign-on, linking a Google Workspace, managing connected agents and revealing stored secrets. This file tells you what Hookie is, how to sign yourself up, and where everything lives. Every link below is absolute.

## Register yourself

1. GET https://app.hookie.ai/v1/agents/register/challenge for a proof-of-work challenge. It is cheap for one agent and costly for a bulk script.
2. Solve it, then POST the solution to https://app.hookie.ai/v1/agents/register with your acceptance of the Terms of Use (https://hookie.ai/legal/terms). The exact request and response fields are in the OpenAPI document.
3. You get a workspace on the Free plan with a Default project, an API credential and a one-time claim link for a human. Both are shown once: keep them. Hookie stores only a hash of the credential.
4. Send the credential as `Authorization: Bearer <credential>` to the REST API, the hosted MCP server or the CLI, and build.

Billing is never available to an agent credential; a person upgrades by opening the claim link. Registration is rate limited and capped daily, and the Free plan quotas apply in full.

## Build

- [Hosted MCP server](https://app.hookie.ai/mcp): Streamable HTTP. The same tools as the CLI, run through the same handlers as the console. Authorization: Bearer <credential>.
- [OpenAPI 3.1 document](https://hookie.ai/openapi.json): every public route: ingest, streaming, the admin API and agent registration.
- [REST API reference](https://docs.hookie.ai/api-reference): the admin API lives under https://app.hookie.ai/admin/api; about 100 requests per 10 seconds per credential, Idempotency-Key on POST.
- [CLI](https://hookie.ai/cli): install with `npm i -g https://app.hookie.ai/cli/hookie-cli.tgz`; for a credential, set HOOKIE_TOKEN and HOOKIE_ALLOW_REMOTE=1. --json on every command.
- [Quickstart](https://docs.hookie.ai/quickstart): create a project, send a test event, find its record, watch a signed delivery arrive.
- [API keys](https://docs.hookie.ai/api-keys): roles, project scope, expiry, IP allowlists and idempotent retries for bearer credentials.
- [Verify signatures](https://docs.hookie.ai/signatures): check Hookie's outbound Hookie-Signature or Standard Webhooks headers.
- [Agents page](https://hookie.ai/agents): the same welcome, for the person reviewing what you are about to do.

## Free plan

- 1,000 events / month (no grace: past it, new events are refused with 429 until the reset)
- 1,000 deliveries / month (past it, deliveries are held, not dropped)
- 1 outbound destination
- 1 live stream connection
- 100,000 AI tokens / month and 100 AI trigger runs / month
- 25 workflow runs in progress at once
- 7-day data retention
- 1 workspace member
- No PostgreSQL source connectors (Pro and Team)

Monthly allowances reset at 00:00 UTC on the 1st. [Pricing](https://hookie.ai/pricing) and [Limits and plans](https://docs.hookie.ai/limits-and-plans) have every number for Free, Pro and Team.

## House rules

- [Terms of Use](https://hookie.ai/legal/terms): registering means accepting them; the request records which version you accepted.
- [Acceptable Use Policy](https://hookie.ai/legal/acceptable-use): what Hookie may not be used for. Breaking it can get a workspace suspended.
- [Privacy Policy](https://hookie.ai/legal/privacy)
- [Security](https://hookie.ai/security): report a vulnerability to security@hookie.ai; anything else to support@hookie.ai.

## Optional

- [llms-full.txt](https://hookie.ai/llms-full.txt): this file plus the full agent guide inline: registration, a first pipeline over REST, MCP and the CLI, limits, concepts and the FAQ.
- [Docs index for LLMs](https://docs.hookie.ai/llms.txt): every documentation page, as markdown.
- [Complete docs for LLMs](https://docs.hookie.ai/llms-full.txt): the whole documentation in one file.
- [Docs search MCP server](https://docs.hookie.ai/mcp): searches the documentation only; it is not the Hookie API.
- [Connected agents](https://docs.hookie.ai/connected-agents): act for a person's existing account over OAuth instead of registering your own.
- [OAuth protected-resource metadata](https://app.hookie.ai/.well-known/oauth-protected-resource): RFC 9728 discovery for the MCP server.
- [Status](https://hookie.ai/status)
- [Changelog](https://hookie.ai/changelog)

---

# The Hookie agent guide

## How Hookie fits together

- Workspace: your account. A self-registered agent owns one, on the Free plan.
- Project: the unit everything belongs to. Every workspace has a Default project; create more for separate pipelines.
- Endpoint: a public URL, app.hookie.ai/{workspace}/{project}/{endpoint-slug}. The long random slug is the credential, so a sender needs no key and no SDK. Anything that can POST can send to it.
- Dataset and record: each event is stored whole as a submission, then filed as records into the dataset its endpoint or rules choose. Records are searchable and exportable.
- Rule: decides which dataset an event lands in and what shape it takes. Empty conditions match everything; empty mappings keep the whole payload.
- Destination and delivery: a destination is where records go next (an HTTPS endpoint, Slack, S3-compatible storage, SQS or Pub/Sub). A delivery is one event sent to one destination, signed, retried with backoff for about a day, and replayable.
- Workflow and AI trigger: multi-step, event-driven processing with branches, HTTP calls and AI steps, and AI triggers that read each arrival and write their result back as a record.

## Registering, step by step

1. GET https://app.hookie.ai/v1/agents/register/challenge. The response is a challenge and how to solve it.
2. POST https://app.hookie.ai/v1/agents/register with the solution and your acceptance of the current Terms of Use (https://hookie.ai/legal/terms). Retrying a registration never creates a second account.
3. Read the response once and store what it returns: the API credential and the claim link are never shown again.
4. Use the credential everywhere below as HOOKIE_TOKEN.

The request and response schemas are in https://hookie.ai/openapi.json. A refusal says why, for example a stale or wrong proof of work, too many registrations from one address, the day's cap reached, or registration switched off by the operator.

## A first pipeline over REST

Create a project. A webhook project comes with one endpoint, so it has a URL at once:

```sh
curl -s https://app.hookie.ai/admin/api/projects -H "Authorization: Bearer $HOOKIE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Orders", "type": "webhook"}'
```

Add an endpoint that files into a dataset of your choosing. The response carries its public_url:

```sh
curl -s https://app.hookie.ai/admin/api/projects/$PROJECT_ID/webhooks -H "Authorization: Bearer $HOOKIE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Checkout", "dataset": "orders"}'
```

Send it an event the way any sender would:

```sh
curl -s -X POST "$PUBLIC_URL" -H "Content-Type: application/json" \
  -d '{"order": 1042, "total": 99.5}'
```

Forward the dataset to a URL of yours. The response shows the destination's signing secret once; verify deliveries with it:

```sh
curl -s https://app.hookie.ai/admin/api/projects/$PROJECT_ID/destinations -H "Authorization: Bearer $HOOKIE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My service", "type": "webhook", "url": "https://example.com/hooks/hookie", "datasetFilter": ["orders"]}'
```

The Free plan allows one destination. Every admin API response carries Hookie-Version; send the same header to pin a version. A POST may carry an Idempotency-Key, and a retry with the same key replays the first answer instead of running twice. Over about 100 requests per 10 seconds per credential the answer is 429 with Retry-After.

## Over MCP

The hosted server is https://app.hookie.ai/mcp (Streamable HTTP). A client that takes a JSON configuration:

```json
{
  "mcpServers": {
    "hookie": {
      "type": "http",
      "url": "https://app.hookie.ai/mcp",
      "headers": {
        "Authorization": "Bearer <credential>"
      }
    }
  }
}
```

Claude Code:

```sh
claude mcp add --transport http hookie https://app.hookie.ai/mcp --header "Authorization: Bearer <credential>"
```

The tools are the CLI's commands: projects, endpoints, rules, destinations, workflows, record search, deliveries and replay. A call runs through the same handler as the console, so it gets the same validation and leaves the same audit trail.

## With the CLI

```sh
npm i -g https://app.hookie.ai/cli/hookie-cli.tgz
export HOOKIE_TOKEN=<credential> HOOKIE_ALLOW_REMOTE=1
hookie projects list --json
hookie endpoints create --name Checkout --slug checkout --dataset orders
hookie deliveries search --status failed --since 24h
hookie replay --since 1h --failed
```

A destructive command with no one to ask refuses unless given --yes. Exit codes: 0 ok, 2 usage, 3 auth, 4 not found, 5 validation, 6 network.

## Limits, and what happens at them

- 1,000 events / month (no grace: past it, new events are refused with 429 until the reset)
- 1,000 deliveries / month (past it, deliveries are held, not dropped)
- 1 outbound destination
- 1 live stream connection
- 100,000 AI tokens / month and 100 AI trigger runs / month
- 25 workflow runs in progress at once
- 7-day data retention
- 1 workspace member
- No PostgreSQL source connectors (Pro and Team)

Every monthly allowance resets at 00:00 UTC on the 1st. Past the event quota, an endpoint answers 429 with the reset time and nothing is stored; a sender that retries after the reset gets in. Past the delivery allowance, events are still stored and their deliveries are held, to be sent once there is room. Creating one resource more than the plan allows is refused with the reason, and what already exists keeps running.

## Questions agents ask

### Can an AI agent sign up for Hookie without a human?

Yes. Ask https://app.hookie.ai/v1/agents/register/challenge for a proof-of-work challenge, solve it, and send the solution to https://app.hookie.ai/v1/agents/register together with your acceptance of the Terms of Use. You get your own workspace on the Free plan, with a Default project, and an API credential that is shown once.

### Which plan does a self-registered agent start on?

The Free plan, with its quotas in full: 1,000 events and 1,000 deliveries a month, 1 outbound destination and 7-day retention. No credit card is involved.

### Can an agent upgrade the plan or pay?

No. Billing is out of reach of every agent credential. Registration also returns a one-time claim link; a person who opens it takes over the account and can upgrade it like any other workspace.

### How does an agent use Hookie once it has a credential?

Send it as an Authorization: Bearer header to the REST API under https://app.hookie.ai/admin/api, to the hosted MCP server at https://app.hookie.ai/mcp, or to the hookie CLI through the HOOKIE_TOKEN environment variable. MCP tools and CLI commands run through the same handlers as the REST API, with the same validation. The REST API covers the most: a few workspace-level reads, such as the audit log, the dashboard and the workspace export, have no MCP tool or CLI command yet.

### Where is the API described?

In the OpenAPI 3.1 document at https://hookie.ai/openapi.json, which is checked against the router on every build, and in the API reference at https://docs.hookie.ai/api-reference.

### Can an agent act for a person instead of registering its own account?

Yes. A coding agent can connect to a person's existing account over OAuth through https://app.hookie.ai/mcp. It starts read-only, the person widens or revokes it in the console, and it never reaches billing. See https://docs.hookie.ai/connected-agents.

## Contact

- Security reports: security@hookie.ai (see https://hookie.ai/security)
- Everything else: support@hookie.ai (see https://hookie.ai/contact)