API · Events
Webhooks
Subscribe to events. Verify signatures. Replay missed deliveries. Stream via SSE.
Last updated
TL;DR. Register a WebhookEndpoint; events arrive HMAC-SHA256 signed via
Matter-Signature: t=,v1=. Per-entity ordering is strictly guaranteed via the
sequence field. Live mode retries for 3 days; test mode retries 3 times. Missed
deliveries can be replayed by cursor.
Every state-changing operation in Matter emits exactly one Event. Register a
WebhookEndpoint to receive them. Signatures are HMAC-SHA256. Delivery is retried for 3
days in live mode, 3 attempts in test mode. Per-entity ordering is strictly guaranteed
via the sequence field, so handlers can apply events in arrival order without
re-fetching to reconcile.
Register an endpoint
POST /v1/webhook_endpoints
{
"url": "https://yoursite.example.com/webhooks/matter",
"description": "Production compliance bot",
"enabled_events": ["entity.state_changed", "filing.*", "compliance.*"],
"api_version": "2026-05-01",
"include": ["data.object"]
}The response includes signing_secret — shown once. Store it securely.
Events may use wildcards: filing.* matches all filing.submitted, filing.accepted,
filing.rejected, etc.
Thin vs fat
By default data.object is thin — {id, object_type} plus a minimal set of the fields most
consumers need to route the event. For the full resource snapshot, set
include: ["data.object"] on the endpoint. You can also always call
GET /v1/events/{id}?expand[]=data.object to inflate an individual event.
Explore
Signing
HMAC-SHA256 details, header anatomy, verification snippets in Node, Python, Go.
Retries & replay
Backoff schedule, delivery attempt visibility, 30-day replay window.
Ordering
Per-entity sequence, exit ordering invariants, SSE streaming for agents.
Event catalog
Every namespace, every type, with canonical payload examples.
Rotating signing secrets
POST /v1/webhook_endpoints/whe_.../rotate_secretThe response carries the new secret. The old secret continues to sign deliveries for 24 hours to give you time to roll the new one through your deployment. See Signing › Rotating secrets for the full rollover procedure.