Miro Webhooks & Events
Overview
Receive real-time notifications when items on a Miro board change. Miro uses board subscriptions via the /v2-experimental/webhooks/board_subscriptions endpoint. All board item types are supported except tags, connectors, and comments.
Prerequisites
- Access token with
boards:read scope
- HTTPS endpoint accessible from the internet
- Webhook signing secret (generated when creating subscription)
Create a Board Subscription
async function createBoardSubscription(boardId: string, callbackUrl: string) {
const response = await fetch(
'https://api.miro.com/v2-experimental/webhooks/board_subscriptions',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.MIRO_ACCESS_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
boardId,
callbackUrl,
status: 'enabled',
}),
}
);
const subscription = await response.json();
console.log(`Subscription created: ${subscription.id}`);
console.log(`Type: ${subscription.type}`);
return subscription;
}
Manage Subscriptions
const list = await miroFetch('/v2-experimental/webhooks/board_subscriptions');
const sub = await miroFetch(`/v2-experimental/webhooks/board_subscriptions/${subId}`);
await miroFetch(`/v2-experimental/webhooks/board_subscriptions/${subId}`, 'PATCH', {
status: 'disabled',
});
await miroFetch(`/v2-experimental/webhooks/board_subscriptions/${subId}`, 'DELETE');
Event Payload Structure
When a board item is created, updated, or deleted, Miro sends a POST request to your callback URL:
{
"event": "board_subscription_changed",
"type": "update",
"boardId": "uXjVN1234567890",
"item": {
"id": "3458764500000001",
"type": "sticky_note"
},
"changes": [
{
"property": "data.content",
"previousValue": "Old text",
"newValue": "Updated text"
}
],
"createdAt": "2025-01-15T10:30:00Z",
"createdBy": {
"id": "user-123",
"type": "user"
Event Types
type Value | Description | Item Types |
|---|
create | New item added to board | All except tags, connectors, comments |
update | Item content/position/style changed | All except tags, connectors, comments |
delete | Item removed from board | All except tags, connectors, comments |
Webhook Handler (Express.js)
import express from 'express';
import crypto from 'crypto';
const app = express();
app.post('/webhooks/miro',
express.raw({ type: 'application/json' }),
async (req, res) => {
const signature = req.headers['x-miro-signature'] as string;
if (!verifySignature(req.body, signature)) {
console.error('Invalid webhook signature — possible forgery');
return res.status(401).json({ error: 'Invalid signature' });
}
const event = JSON.parse(req.body.toString());
res.status(200).json({ received: true });
processEvent(event).catch(
.()
);
}
);
(): {
(!signature) ;
secret = process..!;
expected = crypto
.(, secret)
.(rawBody)
.();
{
crypto.(
.(signature, ),
.(expected, ),
);
} {
;
}
}
Event Processing
interface MiroBoardEvent {
event: 'board_subscription_changed';
type: 'create' | 'update' | 'delete';
boardId: string;
item: { id: string; type: string };
changes?: Array<{ property: string; previousValue: unknown; newValue: unknown }>;
createdAt: string;
createdBy: { id: string; type: string };
}
async function processEvent(event: MiroBoardEvent): Promise<void> {
const { type, boardId, item } = event;
switch (type) {
case 'create':
console.log(`New ${item.type} created on board ${boardId}: ${item.id}`);
const fullItem = await ();
(fullItem);
;
:
.();
(event.) {
( change event.) {
.();
}
}
(item., event.);
;
:
.();
(item.);
;
}
}
Idempotency Guard
Miro may deliver the same event multiple times. Prevent duplicate processing:
import { Redis } from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);
async function processOnce(eventId: string, handler: () => Promise<void>): Promise<void> {
const key = `miro:webhook:${eventId}`;
const result = await redis.set(key, '1', 'EX', 86400 * 7, 'NX');
if (result !== 'OK') {
console.log(`Duplicate event ${eventId} — skipping`);
return;
}
await handler();
}
Webhook Testing
ngrok http 3000
curl -X POST http://localhost:3000/webhooks/miro \
-H "Content-Type: application/json" \
-H "X-Miro-Signature: $(echo -n '{"event":"board_subscription_changed","type":"create","boardId":"test","item":{"id":"123","type":"sticky_note"}}' | openssl dgst -sha256 -hmac "$MIRO_WEBHOOK_SECRET" | awk '{print $2}')" \
-d '{"event":"board_subscription_changed","type":"create","boardId":"test","item":{"id":"123","type":"sticky_note"}}'
Error Handling
| Issue | Cause | Solution |
|---|
| No events received | Subscription disabled | Check subscription status |
| Invalid signature | Wrong secret | Verify MIRO_WEBHOOK_SECRET matches app settings |
| Event processing timeout | Slow handler | Return 200 immediately, process async |
| Duplicate events | Miro retry delivery | Implement idempotency with event ID |
| Missing item types | Tags/connectors/comments excluded | Use polling for those types |
Resources
Next Steps
For performance optimization, see miro-performance-tuning.
