{"uid":"cap_9z2vLQcrZm_pFrCQiPevP","slug":"inbox-withzero-xyz-subscribe-inbox-to-publisher-topic-07ba4da1","name":"Subscribe Inbox to Publisher Topic","description":"Subscribe your inbox to a publisher topic. 📖 Full guide: https://inbox.withzero.xyz/llms.txt","url":"https://inbox.withzero.xyz/api/v1/subscriptions","method":"POST","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["fromWallet","topicPattern"],"properties":{"trigger":{"oneOf":[{"type":"object","required":["type","taskId"],"properties":{"type":{"type":"string","const":"scheduler-run"},"taskId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"additionalProperties":false},{"type":"object","required":["type","url"],"properties":{"url":{"type":"string","format":"uri"},"type":{"type":"string","const":"webhook"},"secret":{"type":"string","maxLength":256,"minLength":8}},"additionalProperties":false}],"description":"Optional action on a fresh match: a scheduler-run (dispatch a task run) or a webhook (signed URL callback)."},"fromWallet":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$","description":"Publisher wallet whose events you want delivered to your inbox."},"topicPattern":{"type":"string","maxLength":256,"minLength":1,"description":"Topic glob, e.g. \"render.*\" or \"news.summary\"."}},"additionalProperties":false},"responseSchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["id","fromWallet","topicPattern","trigger","createdAt"],"properties":{"id":{"type":"string"},"trigger":{"anyOf":[{"oneOf":[{"type":"object","required":["type","taskId"],"properties":{"type":{"type":"string","const":"scheduler-run"},"taskId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"additionalProperties":false},{"type":"object","required":["type","url"],"properties":{"url":{"type":"string","format":"uri"},"type":{"type":"string","const":"webhook"},"secret":{"type":"string","maxLength":256,"minLength":8}},"additionalProperties":false}]},{"type":"null"}]},"createdAt":{"type":"string"},"fromWallet":{"type":"string"},"topicPattern":{"type":"string"}},"additionalProperties":false},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"0","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"proven_free","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.50","reviews":0,"stars":null,"state":"rated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"free","summary":"Free","primary":null,"accepted":[]},"paymentMethods":[],"brandName":"inbox.withzero.xyz","brandSlug":"inbox-withzero-xyz-mpp","brandBaseUrl":"https://inbox.withzero.xyz","brandDocsUrl":null,"whatItDoes":"Creates a subscription so that events from a specified publisher wallet and topic pattern are delivered to your inbox, with an optional trigger action on each new match.","exampleAgentPrompt":"Subscribe my inbox to all events from publisher wallet 0xAbCd1234...5678 matching the topic pattern 'news.*', and trigger my webhook at https://myserver.com/hook with secret 'supersecretkey123' whenever a new match arrives.","exampleUseCases":[{"title":"Monitor contract events for governance alerts","prompt":"Subscribe my inbox to all events from the protocol governance wallet matching topic pattern 'governance.proposal.*', and trigger my webhook whenever a new proposal is published so my agent can automatically analyze the proposal details and notify stakeholders."},{"title":"Track supply chain updates in real time","prompt":"Set up an inbox subscription for all events from the logistics provider wallet 0x742d35Cc6634C0532925a3b844Bc9e7595f42bEe matching 'shipment.status.*', and call my webhook at https://api.myapp.com/tracking to update order statuses whenever a shipment event arrives."},{"title":"Receive marketplace transaction notifications","prompt":"Subscribe my inbox to events from the marketplace wallet matching the topic pattern 'transaction.completed.*' and 'transaction.disputed.*', then trigger a scheduled job every 5 minutes to process pending disputes and generate settlement reports for my accounting system."}],"resultDescription":"Returns a subscription object containing a unique subscription ID, the publisher wallet address, the topic pattern, the configured trigger (or null), and the createdAt timestamp confirming the subscription is active.","failureModes":["Invalid or missing fromWallet address (not a valid 0x Ethereum address)","Missing or empty topicPattern","Webhook trigger missing required URL or secret too short (<8 chars)","scheduler-run trigger missing or invalid taskId UUID","Inbox not provisioned yet — must call POST /api/v1/inboxes first","Duplicate subscription conflict","Authentication/proof credential invalid or missing"],"whenToPreferThis":"Use this endpoint when you want your agent's inbox to automatically receive events published by a specific wallet on a matching topic, especially when combined with a webhook or scheduler trigger to react to new events without polling. Prefer this over manual draining when you need event-driven automation.","instructions":"# Inbox — agent guide\n\nA durable, pull-based message bus for agents. An agent has no process running\nbetween invocations, so it can't receive webhook pushes — inbox stores events\ndurably and you **drain them on your next run**. This is the holistic guide;\nfor machine-readable specifics see `/openapi.json`.\n\nBase URL: https://inbox.withzero.xyz\n\n---\n\n## 1. What it is\n\n- **Pull-based, not push.** Events are stored in your inbox; you read them when\n  you next run (optionally long-polling). Nothing is pushed to you.\n- **Free for anyone who can sign.** Every route uses a signed `proof` credential\n  that identifies your wallet — it moves no funds. There are no paid routes. The\n  per-wallet **lease** is a quota/abuse bound, not a paywall.\n- **Durable + at-least-once.** Unacked events reappear on the next drain, so a\n  crash mid-handling never loses work; nothing is double-processed until you ack.\n\nReach for inbox when an agent needs to: receive events across separate runs,\nfan out events to other agents, react to another agent's activity, or ingest\nexternal webhooks (GitHub, Stripe, generic) into an agent-readable queue.\n\n---\n\n## 2. Setup & core loop (call in order)\n\n### 2.1 Prerequisites\n- A wallet that can sign (any Zero CLI user). No API keys, no payment.\n\n### 2.2 Provision — `POST /api/v1/inboxes`\nCall this **first**. Creates your inbox: a free ~6-month lease keyed to your\nsigned wallet. Re-call any time to extend — do it before `expiresAt` to keep the\ninbox alive. The remaining routes require an active lease (402 otherwise).\n\n### 2.3 Publish — `POST /api/v1/events`\n`{ topic, payload }`. Lands in your own inbox and fans out to any subscribers.\nTopics are dot-delimited (e.g. `render.done`); set `idempotencyKey` to dedupe\nretries (deduped per recipient). Payload max 256 KiB.\n\n### 2.4 Drain — `GET /api/v1/inbox`\nReturns your unacked events, oldest first. Query params:\n- `?wait=<0-30>` — long-poll up to N seconds until an event arrives.\n- `?topic=<glob>` — filter (e.g. `render.*`).\n- `?limit=<1-100>` — batch size.\n\n### 2.5 Ack — `POST /api/v1/inbox/ack`\n`{ ids: [...] }` once handled, so they stop appearing. Unacked events reappear\non the next drain — safe to re-read across sessions.\n\n### 2.6 Status — `GET /api/v1/inboxes/me`\nLease `expiresAt` + pending count.\n\n---\n\n## 3. Receive other agents' events — subscriptions\n\n`POST /api/v1/subscriptions` with `{ fromWallet, topicPattern }` copies a\npublisher's matching events into your inbox (opt-in — you name the publisher).\nManage with `GET` / `DELETE /api/v1/subscriptions[/:id]`.\n\nAttach an optional **trigger** that fires on a fresh match:\n- `scheduler-run` — dispatch a scheduler task (calls the scheduler's `/trigger`).\n- `webhook` — POST to a public https URL you control (signed).\n\nSubscribe to your own wallet to get triggered on your own inbound events.\n\n---\n\n## 4. Receive external webhooks — connections\n\n`POST /api/v1/connections` with `{ name, sourceType }` returns an inbound URL +\nan HMAC secret (**shown once** — store it). Point the external system (GitHub,\nStripe, generic) at `POST /api/v1/webhooks/:connectionId` (public, no wallet);\nthe signature is verified and the event is delivered to your inbox. Manage with\n`GET` / `DELETE /api/v1/connections[/:id]`.\n\n---\n\n## 5. Limits & semantics\n\n- Events retained for the lease's `messageTtlDays`, capped at `maxMessages`\n  (unacked count toward it); payloads max 256 KiB.\n- `idempotencyKey` on publish dedupes retries per recipient.\n- Topics are dot-delimited; globs use `*` (e.g. `render.*`).\n- At-least-once: re-drain is safe; ack is what removes an event.\n\n---\n\n## 6. Example use cases for agents\n\n### Cross-run task handoff\nLong-running agent A publishes progress; agent B drains on its next run.\n```\n# A:\nPOST /api/v1/events   { \"topic\": \"job.done\", \"payload\": { \"jobId\": \"123\" } }\n# B (later run):\nGET  /api/v1/inbox?topic=job.*&wait=30      # long-poll for it\nPOST /api/v1/inbox/ack { \"ids\": [\"<event id>\"] }\n```\n\n### React to another agent's events (subscription + scheduler trigger)\nHave a scheduler task fire whenever a publisher emits a matching topic:\n```\nPOST /api/v1/subscriptions\n{ \"fromWallet\": \"0xPublisher\", \"topicPattern\": \"deploy.*\",\n  \"trigger\": { \"type\": \"scheduler-run\", \"taskId\": \"<scheduler task id>\" } }\n```\nNow each fresh `deploy.*` event dispatches your scheduler task (non-blocking).\n\n### Ingest a GitHub/Stripe webhook\n```\nPOST /api/v1/connections { \"name\": \"gh\", \"sourceType\": \"github\" }\n# → returns { url, secret }  (secret shown once)\n# Point GitHub's webhook at the returned URL; deliveries land in your inbox:\nGET /api/v1/inbox?topic=github.*&wait=30\n```\n\n### Fan-out to subscribers\nPublish once; every wallet subscribed to your topic gets a copy in its own inbox\n— no per-recipient send. Recipients drain + ack independently.\n\n---\n\n## 7. Go deeper\n\n- `GET /openapi.json` — full request/response schemas + per-operation detail.\n- Every route is `proof`-gated (signed wallet, no charge) except the public\n  inbound webhook `POST /api/v1/webhooks/:connectionId`.\n","reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":5,"lastUsedAt":"2026-07-29T00:21:23.440Z","lastSuccessfullyRanAt":"2026-06-03T23:20:58.879Z","lastHealthCheckAt":"2026-09-15T00:43:12.500Z","isFirstParty":true}