---

name: miro-webhooks-events description: "Design and implement a repository-side replacement for retired Miro REST webhooks using explicit freshness requirements, bounded reconciliation, or in-board Web SDK events. Use when designing Miro change detection. Trigger with "Miro webhooks"." argument-hint: "[event-use-case] [freshness-slo]" allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit version: 1.9.0 author: Jeremy Longshore jeremy@intentsolutions.io license: MIT tags:

• saas
• miro
• events
• web-sdk
• reconciliation model: inherit effort: high compatibility: Designed for Claude Code; live work requires an authorized Miro app and redacted evidence

---

Miro Eventing Gap and Supported Alternatives

Overview

Prevent new systems from depending on Miro's discontinued experimental webhook infrastructure. Select an alternative that honestly represents durability and freshness; use the evidence produced here to make the next decision explicit and reviewable.

Prerequisites

• Event use case, consumers, and freshness/loss tolerance
• Current REST and Web SDK capability inventory
• Authorized boards, rate budget, and reconciliation state store

Tool Discipline

Use Read, Glob, and Grep to inspect the repository, configuration names, adapters, tests, and evidence. Use WebFetch only for current official Miro documentation. Use Write or Edit after confirming the requested mode, target environment, tenant, board, and approval boundary. These declared tools do not call authenticated Miro APIs or deployment CLIs; implement client, configuration, and test changes, then return exact operator commands or an approval-gated handoff for live execution.

Current Contract

• Miro discontinued experimental REST webhooks and /v2-experimental/webhooks/board_subscriptions.
• There is no current production Miro REST callback/signature contract documented as its replacement.
• Web SDK UI events such as items:create and items:delete run in active board app contexts; they are not durable server-to-server delivery.
• experimental:items:update remains experimental, and items:create does not fire for copy-paste or duplication.

Authentication

For REST work, use OAuth 2.0 Authorization Code with the narrowest Miro scopes. Bind each encrypted token record to its user, application, authorized team, and granted scopes. Never print access tokens, refresh tokens, client secrets, authorization codes, or board content.

Instructions

1. Inventory every retired subscription call, callback handler, signature assumption, queue, and downstream consumer.
2. Define required freshness, completeness, replay, ordering, and active-board assumptions.
3. Choose bounded REST reconciliation for durable server state or supported Web SDK UI events for active in-board behavior.
4. For polling, store normalized checkpoints, traverse cursors safely, budget credits, and run periodic full reconciliation.
5. For Web SDK events, register and unregister stable handlers, tolerate duplicates/misses, and label session-only semantics.
6. Remove retired endpoints and secrets; test detection gaps and publish the residual freshness/loss contract.

Approval Boundaries

Do not reactivate retired endpoints, invent a signature header, market session events as durable delivery, or increase polling load without owner approval. Pause when the responsible owner or exact target is uncertain.

Output

Return retired dependency inventory, chosen alternative, freshness/loss guarantee, rate budget, checkpoint design, tests, and migration plan. State what was not inspected or changed so the receipt cannot overclaim coverage.

Error Handling

Condition	Response
Retired endpoint is still called	Disable that path and move the consumer to reconciliation or an approved alternative.
Consumer requires lossless real time	Report that current documented capabilities do not satisfy it.
Web SDK event misses duplication	Reconcile rather than claiming completeness.
Polling nears credit limit	Slow the schedule, narrow reads, or renegotiate freshness.

Examples

The example is a redacted operator receipt; identifiers are hashes or bounded labels, not board content or credentials.

retired-subscriptions=3; replacement=cursor-reconcile; interval=5m; full-scan=24h; credit-headroom=35%; lossless=no

Resources

• Skill-specific official documentation
• Webhooks removal
• Web SDK UI events