# AGNT Webhooks — agent instructions
Base: https://webhooks.agnt.gg/hooks/v1 · Public ingress: https://webhooks.agnt.gg/in/<slug> · OpenAPI: https://webhooks.agnt.gg/openapi.json
Product: a durable, signed inbound HTTPS endpoint an agent owns. Events are stored and billed exactly once before acknowledgement, kept for the plan's retention window, delivered to registered receivers with HMAC signatures and retries, and readable over the API at any time.

## Signup (no human)
POST /agents {"name":"my-agent"} → 201 {agentId, secret:"hook_…" (shown once), fund:{claimUrl, x402:"POST /hooks/v1/funding/x402"}}. Use `Authorization: Bearer <secret>` for everything below. The agent secret carries hook:read, hook:emit, hook:manage.

## Fund and activate
Option A (human): share fund.claimUrl; the owner pays by card or stablecoin wallet. Poll GET /agents/<agentId>/claim until hostingActive:true.
Option B (x402, USDC on Base, no human): POST /funding/x402 {"amountCents":1000|2500|5000} → 402 {orderId, requirements}. Pay with any x402 v2 client (JS: @x402/fetch + @x402/evm; call setSpendControls({maxAmountPerPayment:'$50'}) first — the default $1 cap refuses every order). POST /funding/x402/<orderId> with PAYMENT-SIGNATURE → 200 {state:"credited"}. Wallet needs USDC only; facilitator pays gas. Retry the same order after a timeout; never create a second order to pay again. Check GET /capabilities autonomousFunding before relying on this.
Then: POST /hosting/purchase {"plan":"starter"|"pro"|"business"} with header Idempotency-Key. GET /usage shows balance and hosting.

## Endpoints
POST /endpoints {"name":"orders"} → 201 {id, slug, url:"https://webhooks.agnt.gg/in/<slug>", state:"provisioning"}. Poll GET /endpoints until state:"active" (seconds). Name: 3–40 lowercase letters, digits, hyphens. Plan caps: Starter 1, Pro 3, Business 10.
POST /endpoints/<id>/pause · POST /endpoints/<id>/resume · DELETE /endpoints/<id> (slug never reused).

## Receiving (public, unauthenticated)
POST https://webhooks.agnt.gg/in/<slug> with JSON, form-encoded or text body ≤ 256 KB. Optional Idempotency-Key header (else the body hash deduplicates). → 202 {eventId, state:"stored"} first time; 200 with the same eventId on repeats (no new charge). Errors: 404 endpoint_not_found, 413, 415, 402 (owner plan exhausted or inactive), 429 rate_limited (60/600/6000 per minute by plan), 503 ingress_unavailable. Bodies are stored as bytes and never executed or fetched.

## Reading
GET /endpoints/<id>/events?after=<received_at> → {events:[{id,source,bytes,content_type,received_at,expires_at}]} oldest first, 100 per page.
GET /events/<id> → {id,endpointId,source,contentType,bytes,receivedAt,expiresAt,body} where body is the raw posted string.
POST /events/<id>/replay → re-queue to all active receivers (Pro/Business only; Starter gets 409 replay_requires_pro).
GET /endpoints/<id>/export?since=0 → NDJSON with bodies (owner login required).
Retention: 7 / 30 / 90 days by plan. Expired events are purged; export first if needed.

## Receivers (push delivery)
POST /webhooks {"url":"https://…"} → 201 {id, secret}. Every stored event is delivered as JSON {id,type:"event.received"|"event.emitted"|"receiver.paused",eventId,endpointId,body}. Headers: X-AGNT-Event-ID, X-AGNT-Timestamp, X-AGNT-Signature: v1=hex(HMAC-SHA256(secret, timestamp+"."+rawBody)). Verify, reject stale timestamps, deduplicate on event ID. At-least-once; backoff 60s→1h; 3 attempts (Starter) or 12 (Pro/Business). After 5 consecutive exhausted events the receiver is paused (receiver.paused event); POST /webhooks/<id>/resume re-queues. Public HTTPS:443 only; private networks and redirects are rejected.
GET /webhook-deliveries · GET /notifications?after=0 · DELETE /webhooks/<id>.

## Emit
POST /emit {"type":"task.completed","data":{…}} (hook:emit) → 202 {eventId,endpointId,type}. Delivered to receivers as event.emitted. Body ≤ 64 KB. One unit for the event + one per receiver.

## Units and limits
1 unit = one accepted inbound event, or one event delivered to one receiver. Reads free. Starter $5/1,000 units/mo; Pro $15/5,000; Business $39/20,000. Overage $0.50 per 1,000 only if PUT /hosting/preferences {"allowOverage":true}. Storage 250 MB / 1 GB / 3 GB pooled. Units reset day 1 UTC. Hosting is prepaid from credit; never an automatic card charge.

## Errors
JSON {error:"snake_case"} with HTTP 400 invalid input · 401 auth · 402 payment/plan · 403 scope · 404 not found · 409 conflict/limit · 413 too large · 415 media type · 429 rate limited · 503 unavailable.