# Wake hooks

Start a sleeping agent when its inbox has work, without paying for it to poll.

Agents that sleep can't poll. A **wake hook** has Ensue call you when the inbox has waiting events, so you can start the agent, which then pulls the events normally.

The wake call carries no event data. Leases, acks and redelivery work exactly as for any pull.

## Set it up

Turn on wake in the inbox's **Wake** tab, or through the API:

```json
{ "wake": { "enabled": true, "url": "https://agent.example.com/wake", "after_seconds": 30 } }
```

Ensue sends a signed `POST` once the inbox has been quiet for `after_seconds` (default 30), or `max_seconds` (default 300) after a burst began. It never wakes while a pull is open. A wake nobody answers with a pull is sent again later, waiting longer each time, up to an hour.

```json
{
  "type": "inbox.wake",
  "inbox": "ibx_…",
  "pending": 3,
  "oldest_at": "2026-11-02T10:00:00Z",
  "newest": { "event_id": "evt_…", "type": "payment_intent.succeeded", "priority": 0 }
}
```

Verify the `x-ensue-signature` header (`t=<timestamp>,v1=<hex>`, an HMAC-SHA256 of `"<timestamp>.<body>"`) as you would for [Gateway deliveries](/gateway/quickstart/).

## No public address

An agent on a laptop or in a sandbox can listen instead of exposing a URL. It opens an outbound stream and gets the same signal:

```text
GET /v1/agent/inbox/:id/ready      (server-sent events)
```

## Loop protection

An agent that is woken many times with no person in between may be waking itself, because its own output lands in its inbox. After a limit, Ensue stops waking it and notifies you.

| Mode | Stops after |
|---|---|
| `headless` (default) | 12 wakes in an hour |
| `interactive` | 3 wakes in a row with no human turn |

Resume from the dashboard, or with `POST /v1/agent/inbox/:id/wake/resume`.

> [!TIP]
> Starters for Claude Code and Cloudflare Agents are in the repo's `starters/` folder.