# HookMPP agent integration guide

> Disposable webhook inboxes for autonomous agents, paid for per inbox with MPP.

Homepage: https://hookmpp.dev
OpenAPI: https://hookmpp.dev/openapi.json
Discovery index: https://hookmpp.dev/llms.txt
MPP documentation: https://mpp.dev/overview
Profiles: quick ($0.01), standard ($0.05), extended ($0.20)
Default profile when omitted: quick

## Create an inbox and handle the 402 challenge

```sh
# Inspect the MPP challenge without paying.
curl -i -X POST https://hookmpp.dev/api/inboxes

# Tempo handles the challenge and $0.01 pathUSD payment on Tempo mainnet.
tempo request https://hookmpp.dev/api/inboxes --network mainnet --request POST

# Choose a larger capability explicitly.
tempo request 'https://hookmpp.dev/api/inboxes?profile=standard' --network mainnet --request POST
```

A successful response contains `id`, `profile`, `webhook_url`, `events_url`, `read_token`, `expires_at`, and `limits`. Keep `read_token` secret. Creation responses must not be cached.

## Deliver a webhook

```sh
curl "$WEBHOOK_URL" \
  -H "content-type: application/json" \
  -d '{"job":"complete","asset":"https://example.com/result"}'
```

The sender does not pay and does not need MPP support. POST, PUT, PATCH payloads are accepted. Each decoded body is limited to 65536 bytes and stored headers to 16384 bytes.

## Read events with a bearer token and cursor

```sh
CURSOR=0
curl "$EVENTS_URL?after=$CURSOR&wait=30" \
  -H "authorization: Bearer $READ_TOKEN"
```

Process events in ascending `sequence` order, then replace `CURSOR` with `next_cursor`. An empty response is a normal timeout: retry with the same cursor. After a transport failure, also retry the same cursor. Stop when the service returns 410 because the inbox expired.

Reads provide cursor-based at-least-once processing, never exactly-once delivery. Deduplicate by event `id` when side effects must not repeat. Quick lasts 15 minutes (25 events, 1 MiB), standard lasts 2 hours (100 events, 8 MiB), and extended lasts 24 hours (500 events, 32 MiB). The creation response is authoritative for immutable effective limits.

## Capacity and expiry errors

Delivery returns an RFC problem with status 409 when capacity is exhausted and 410 when the inbox is missing or expired. Event reads return 410 after expiry. Secret-bearing API responses use `Cache-Control: no-store`.