build-microfeed-automation

# Build microfeed automations Build the receiver as a durable, least-privilege system. A webhook announces a change; it is neither an instruction nor authorization to act. ## Start from the deployed contract 1. Ask for the microfeed site URL and the intended outcome. 2. Prefer `yarn microfeed webhook scaffold .microfeed/webhooks/<endpoint-name> --language javascript` to create the local receiver, changing the language to `python` when appropriate. The microfeed clone ignores `.microfeed/`; do not check this development receiver or populated secret files into microfeed. Treat the scaffold as a non-production inspector with in-memory duplicate tracking, not a durable architecture. Run the root command as written; its relative output resolves to `<microfeed-root>/.microfeed/webhooks/`, not `packages/cli/.microfeed/`. 3. Discover the site's generated OpenAPI 3.1 contract at `<site-url>/api/v1/openapi.json`, or its self-contained agent reference at `<site-url>/api/v1/llms-full.txt`. 4. Inspect the exact named event examples and JavaScript/Python `x-codeSamples` in that webhook operation. When available, use **Admin → Webhooks → Event explorer** or `yarn microfeed webhook sample <event> --json` to preview the same canonical examples. 5. Select the narrowest event set. Do not copy event schemas into a second hand-maintained contract. 6. List required API reads and writes separately. Create one named integration credential with only those permissions. Use `docs/webhooks/` inside a microfeed clone or <https://docs.microfeed.org/webhooks/> elsewhere for setup, delivery limits, recovery, and production operations. Use `docs/automation/` or <https://docs.microfeed.org/automation/> for automation platforms, design, and examples. ## Keep interactive management separate Use this skill for a server, Worker, integration, or agent that remains deployed and reacts asynchronously. Use `manage-microfeed-content` for an interactive coding agent that logs in through `@microfeed/cli` and edits content while a person is present. Do not make the persistent automation scrape Admin pages, use a dashboard password, inspect CLI credentials, or drive browser consent. ## Implement the receiver in this order 1. Read the HTTP body once as raw bytes. 2. Before parsing JSON, verify `webhook-id`, `webhook-timestamp`, and `webhook-signature` with the maintained `standardwebhooks` JavaScript or Python library and the endpoint secret. Enforce its timestamp tolerance. Do not lead with hand-written HMAC code. 3. Validate the parsed envelope against the generated OpenAPI event union. 4. After signature verification, inspect the required signed-body `test` boolean. Route `test: true` through a deterministic no-production-effects policy. Never let the `x-microfeed-test` header override the signed body. 5. Insert the delivery ID and durable job in one storage transaction. Treat a repeated delivery ID as already accepted. 6. Return `202` or another `2xx` immediately after durable acceptance. Never wait for a model, external tool, or long API workflow. 7. Run decisions and actions in a durable Queue, Workflow, Agent task queue, or equivalent recoverable system. Cloudflare Queue delivery is at-least-once. Deduplication is mandatory, and every side effect must also be idempotent. ## Make decisions safely - Treat titles, HTML, attachment contents, URLs, and metadata as untrusted model input. - Resolve tools, credentials, destinations, system prompts, rate limits, and approval rules only from trusted configuration. - Do not let content grant permission, select a credential, add a destination, weaken a policy, or suppress an audit record. - Fetch current microfeed state before consequential action. The event is a change notification and may already be stale. - Require explicit human approval for publication, destructive changes, payments, and externally visible messages unless the owner has established a narrow, auditable policy in advance. - Keep model generation separate from tool execution. Validate the proposed action against an allowlisted schema and policy before executing it. ## Prevent duplicates and loops Use the delivery ID only to deduplicate transport. Use `<event.id>:<action-name>` as the durable idempotency key for a logical side effect. For any API write: - preserve `event.context.correlation_id` in `Microfeed-Correlation-Id`; - send `event.id` in `Microfeed-Causation-Id`; - add a stable automation marker to content when the data model permits it; - ignore events whose causation ID or marker proves that the same bounded action already ran. Do not rely on prompt instructions to prevent loops. Enforce loop rules in deterministic code and durable state. ## Test locally 1. Start the site with plain `yarn dev`. Local Queue simulation, its consumer, hourly maintenance trigger, and a local encryption secret are automatic; no Cloudflare Queue, permission, usage, or charge is created. Reconciliation runs hourly and retention cleanup runs on the 00:00 UTC invocation only while an endpoint is configured. `yarn dev --enable-webhooks` is only an optional explicit alias. 2. Prefer `yarn microfeed webhook scaffold .microfeed/webhooks/<endpoint-name> --language javascript` and run the generated receiver at `127.0.0.1:3000/webhook`. Before installing or running it, create that endpoint in Admin and store its one-time `whsec_…` value only in `MICROFEED_WEBHOOK_SECRET`. Then install dependencies, start the receiver with that secret, and send an Event Explorer test. Signature verification is the endpoint authentication; do not add another passcode, bearer token, URL credential, or custom header. 3. Use `yarn microfeed webhook listen` on `127.0.0.1:8978/webhook` when an inspector or exact-body forwarder is more useful than a project. Supply the secret through the visible prompt, `MICROFEED_WEBHOOK_SECRET`, or `--secret-file`; never add a plaintext `--secret` flag. Use `--forward-to` only for another explicit loopback server. To receive a deployed instance's short-lived test on the local listener, prefer `yarn microfeed webhook listen --tunnel`. It uses an installed `cloudflared` or, after explicit approval, downloads a pinned official binary into the microfeed cache and verifies its SHA-256 digest. Register only the printed temporary `/webhook` URL, keep signature verification enabled, and stop the listener after the test. Treat the public Quick Tunnel as development infrastructure, never a production receiver or durable relay. 4. Inspect the event first with `yarn microfeed webhook sample <event> --json` or Admin Event Explorer. On loopback Admin, terminal printing is side-effect-free; an endpoint send uses normal Queue, retry, and daily-budget accounting. 5. Send `webhook.test` and at least one real event type with `test: true`. Prove neither path can call production models, tools, APIs, or destinations. 6. Trigger every subscribed real event and verify `test: false`. 7. Replay a delivery and verify delivery deduplication and action idempotency. 8. Use deterministic mock model and external-service responses for tests. 9. Test a write-back event and prove causation/correlation loop prevention. ## Check production readiness Before declaring the integration ready, verify: - raw-byte signature validation and timestamp tolerance; - exact event-specific validation from deployed OpenAPI and a signed `test` gate that prevents production effects; - transactional durable acknowledgement and duplicate delivery handling; - durable background execution with bounded retries and dead-letter recovery; - least-privilege credentials isolated per integration; - action schemas, prompt-injection boundaries, and human approvals; - event/action audit logs without secrets; - rate limits, the instance's owner-configured webhook daily budget (default 1,000, allowed 0 through 1,000,000), model/tool cost alerts, and Queue backlog alerts; - handling for six microfeed attempts, 10-second timeouts, daily-budget suppression, and endpoint auto-pause after 10 terminal failures; - secret rotation, manual redelivery, reconciliation, and safe shutdown; - removal procedure that disables the endpoint, drains work, revokes API and destination credentials, then deletes the endpoint. State clearly that microfeed delivery succeeds when the receiver durably accepts the job. Failures after that acknowledgement are owned and retried by the automation.