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.