API · Events · Webhooks
Event catalog
Every namespace, every type, with canonical payload examples.
Last updated
TL;DR. Ten namespaces, ~50 event types. Every event shares the same envelope.
data.object is thin by default — opt into the full snapshot with
include: ["data.object"] on the endpoint, or expand per-event with
?expand[]=data.object on the events API.
This page is the canonical list of every event Matter emits. For envelope semantics, see Webhooks › Event shape.
Envelope
Every event — across every namespace — uses the same envelope:
{
"id": "evt_1Pq3Kc...",
"object": "event",
"type": "<namespace>.<verb>",
"api_version": "2026-05-01",
"created": 1745251200,
"data": {
"object": { "id": "<typed_id>", "object_type": "<resource>", "...": "..." },
"previous_attributes": { "...": "..." }
},
"sequence": 42,
"livemode": true,
"pending_webhooks": 1,
"request": {
"id": "req_Qw9xYz8A",
"idempotency_key": "7a0c3b8e-..."
},
"authorized_by": {
"human_principal_id": "usr_4Kj2m8pQ",
"agent_id": "agt_Nq3KcAbc",
"token_id": "tok_..."
}
}previous_attributes only appears on *.state_changed and equivalent diff-style events.
authorized_by carries the full dual-attribution record — human principal + agent
identity + token — for any event triggered by an authenticated mutation.
entity.*
Lifecycle transitions on the entity itself.
| Type | Description |
|---|---|
entity.created | Draft entity created. data.object.status = "draft". |
entity.state_changed | Any state transition. Carries previous_status. |
entity.submitted | Filed with the secretary of state. |
entity.registered | Certificate issued; entity is real. |
entity.qualified | Foreign qualification accepted in a new jurisdiction. |
entity.dissolved | Terminal — dissolution certificate issued. |
entity.acquired | Sold via M&A. Survives in the buyer's portfolio. |
entity.merged | Merged into another entity. |
entity.sold | Asset sale closed; entity may continue or wind down. |
entity.reinstated | Returned from suspended to active after compliance cure. |
{
"id": "evt_1Pq3Kc...",
"object": "event",
"type": "entity.registered",
"api_version": "2026-05-01",
"created": 1745251200,
"data": {
"object": {
"id": "ent_Nq3KcAbc",
"object_type": "entity",
"status": "registered",
"previous_status": "submitted",
"legal_name": "Waypoint Systems, Inc.",
"jurisdiction": "US-DE",
"entity_type": "c_corp",
"registered_at": 1745251198,
"ein": null,
"incorporator_receipt_id": "rcp_8Kc2m9pQ"
}
},
"sequence": 3,
"livemode": true,
"pending_webhooks": 1,
"request": { "id": "req_Qw9xYz8A", "idempotency_key": "..." },
"authorized_by": { "human_principal_id": "usr_4Kj2m8pQ", "agent_id": null }
}intent.*
The declarative Intent resolver — see Entity intents.
| Type | Description |
|---|---|
intent.created | Intent submitted, awaiting resolution. |
intent.resolved | Execution plan emitted. |
intent.executing | Plan in flight. |
intent.completed | All plan steps committed. |
intent.cancelled | Cancelled by caller before completion. |
intent.failed | Resolution or execution failed. data.object.failure_reason populated. |
{
"id": "evt_1Pq3Kd...",
"object": "event",
"type": "intent.resolved",
"api_version": "2026-05-01",
"created": 1745251100,
"data": {
"object": {
"id": "int_8Kc2m9pQ",
"object_type": "intent",
"status": "resolved",
"execution_plan_id": "plan_9Lc3n0qR",
"target": { "object_type": "entity", "jurisdiction": "US-DE", "entity_type": "c_corp" },
"step_count": 7,
"estimated_completion": "2026-04-25T17:00:00Z"
}
},
"sequence": 1,
"livemode": true,
"pending_webhooks": 1
}filing.*
Every interaction with a secretary of state, IRS, or equivalent agency.
| Type | Description |
|---|---|
filing.submitted | Filing transmitted to the agency. |
filing.accepted | Agency confirmed receipt and acceptance. |
filing.rejected | Agency rejected. data.object.rejection_reason populated. |
filing.amended | Replacement filing accepted, supersedes a prior filing_id. |
filing.cancelled | Withdrawn before agency acceptance. |
{
"id": "evt_1Pq3Ke...",
"object": "event",
"type": "filing.accepted",
"api_version": "2026-05-01",
"created": 1745254800,
"data": {
"object": {
"id": "flg_4Mn5p6qR",
"object_type": "filing",
"status": "accepted",
"kind": "certificate_of_incorporation",
"entity_id": "ent_Nq3KcAbc",
"agency": "DE-SOS",
"agency_reference": "8742199",
"submitted_at": 1745254100,
"accepted_at": 1745254790,
"document_id": "doc_7Pq8r9sT"
}
},
"sequence": 4,
"livemode": true,
"pending_webhooks": 1
}document.*
The Document resource — every legal artifact, queryable as data.
| Type | Description |
|---|---|
document.generated | Rendered to PDF and structured JSON. |
document.signed | All required signatures captured. |
document.voided | Superseded or invalidated. |
{
"id": "evt_1Pq3Kf...",
"object": "event",
"type": "document.signed",
"api_version": "2026-05-01",
"created": 1745255200,
"data": {
"object": {
"id": "doc_7Pq8r9sT",
"object_type": "document",
"kind": "stock_purchase_agreement",
"entity_id": "ent_Nq3KcAbc",
"version": 2,
"signed_at": 1745255199,
"signers": [
{ "stakeholder_id": "stk_2Lc3m4nO", "signed_at": 1745255100 },
{ "stakeholder_id": "stk_3Md4n5oP", "signed_at": 1745255199 }
],
"pdf_url": "https://files.mattermode.com/doc_7Pq8r9sT.pdf",
"json_url": "https://files.mattermode.com/doc_7Pq8r9sT.json"
}
},
"sequence": 9,
"livemode": true,
"pending_webhooks": 1
}cap_table.*
Equity events. Subject is the entity, not the cap-table view (which is computed).
| Type | Description |
|---|---|
cap_table.shares_issued | New shares minted into the ledger. |
cap_table.shares_transferred | Shares moved between stakeholders. |
cap_table.share_class_created | New ShareClass defined. |
cap_table.valuation_filed | New Valuation (409A or priced round) recorded. |
cap_table.grant_issued | Equity grant issued to a stakeholder. |
cap_table.grant_exercised | Grant exercised, converting to shares. |
{
"id": "evt_1Pq3Kg...",
"object": "event",
"type": "cap_table.grant_issued",
"api_version": "2026-05-01",
"created": 1745256000,
"data": {
"object": {
"id": "grt_5Op6q7rS",
"object_type": "grant",
"entity_id": "ent_Nq3KcAbc",
"stakeholder_id": "stk_2Lc3m4nO",
"share_class_id": "cls_1Kb2l3mN",
"kind": "iso",
"shares": 50000,
"strike_price": "0.10",
"vesting_schedule": "4y_1y_cliff_monthly",
"grant_date": "2026-04-24",
"board_resolution_id": "res_6Pq7r8sT"
}
},
"sequence": 12,
"livemode": true,
"pending_webhooks": 1
}compliance.*
Forward-looking deadlines and entity health. Subject is the entity.
| Type | Description |
|---|---|
compliance.deadline_approaching | A deadline within the configured warning window. |
compliance.deadline_missed | A deadline passed without filing. |
compliance.health_changed | Aggregate compliance health rolled up or down. |
{
"id": "evt_1Pq3Kh...",
"object": "event",
"type": "compliance.deadline_approaching",
"api_version": "2026-05-01",
"created": 1745256100,
"data": {
"object": {
"object_type": "compliance",
"entity_id": "ent_Nq3KcAbc",
"obligation": "de_franchise_tax_2026",
"due_at": "2026-06-01T23:59:59Z",
"days_remaining": 38,
"severity": "warning",
"auto_filable": true
}
},
"sequence": 18,
"livemode": true,
"pending_webhooks": 1
}incorporator_receipt.*
The Incorporator Protocol — Matter's signed proof-of-birth chain.
| Type | Description |
|---|---|
incorporator_receipt.issued | Receipt minted at the moment of registration. |
incorporator_receipt.transferred | Authority transferred from incorporator to founders. |
{
"id": "evt_1Pq3Ki...",
"object": "event",
"type": "incorporator_receipt.transferred",
"api_version": "2026-05-01",
"created": 1745251210,
"data": {
"object": {
"id": "rcp_8Kc2m9pQ",
"object_type": "incorporator_receipt",
"entity_id": "ent_Nq3KcAbc",
"issued_at": 1745251198,
"transferred_at": 1745251210,
"transferred_to": ["stk_2Lc3m4nO", "stk_3Md4n5oP"],
"signature_chain": [
{ "role": "matter_incorporator", "signature": "...", "key_id": "kid_..." },
{ "role": "action_of_incorporator", "signature": "...", "key_id": "kid_..." }
]
}
},
"sequence": 5,
"livemode": true,
"pending_webhooks": 1
}authorization.*
Tier-3 mutations are gated by Authorization objects — a human in the loop.
| Type | Description |
|---|---|
authorization.pending | An action is awaiting human approval. |
authorization.approved | Approved; the underlying action will proceed. |
authorization.denied | Denied; the underlying action is cancelled. |
authorization.expired | Time-to-live elapsed without a decision. |
{
"id": "evt_1Pq3Kj...",
"object": "event",
"type": "authorization.pending",
"api_version": "2026-05-01",
"created": 1745257000,
"data": {
"object": {
"id": "auth_3Nm4o5pQ",
"object_type": "authorization",
"status": "pending",
"action": "filings:create",
"subject": { "object_type": "filing", "kind": "annual_report", "entity_id": "ent_Nq3KcAbc" },
"requested_by": { "agent_id": "agt_Nq3KcAbc", "token_id": "tok_..." },
"expires_at": "2026-04-25T17:00:00Z",
"approval_url": "https://app.mattermode.com/auth/auth_3Nm4o5pQ"
}
},
"sequence": 22,
"livemode": true,
"pending_webhooks": 1
}corporate_transaction.*
The M&A envelope. Drives Exit-phase entity events.
| Type | Description |
|---|---|
corporate_transaction.created | Transaction opened (typically at loi). |
corporate_transaction.advanced | Stage transition. Carries from_stage / to_stage. |
corporate_transaction.closed | Closing executed. |
corporate_transaction.cancelled | Closed without consummation; deal terminated cleanly. |
corporate_transaction.terminated | Hard kill — material breach, regulatory block. |
{
"id": "evt_1Pq3Kk...",
"object": "event",
"type": "corporate_transaction.closed",
"api_version": "2026-05-01",
"created": 1745260000,
"data": {
"object": {
"id": "ctx_4Op5q6rS",
"object_type": "corporate_transaction",
"kind": "stock_purchase",
"stage": "closed",
"previous_stage": "closing",
"buyer_entity_id": "ent_BuyerCorp",
"target_entity_id": "ent_Nq3KcAbc",
"consideration": { "currency": "USD", "amount": "42000000.00", "form": "cash_and_stock" },
"closed_at": 1745259998,
"definitive_agreement_id": "doc_DefAgr123",
"filings": ["flg_StockPurchase456"]
}
},
"sequence": 30,
"livemode": true,
"pending_webhooks": 1
}The next event on the target entity's sequence will be entity.acquired. See
Ordering › Exit ordering.
vesting_overlay.*
Retroactive vesting layered onto previously-issued shares. The cap-table side
of an overlay is queryable via GET /entities/{id}/cap_table?expand[]=vesting_overlays.
| Type | Description |
|---|---|
vesting_overlay.created | Overlay accepted; recipient counter-signature pending. |
vesting_overlay.executed | Recipient counter-signed; overlay now binds. |
vesting_overlay.voided | Overlay cancelled before binding (rare; e.g., authorising Resolution rescinded). |
{
"id": "evt_1Pq3Kv...",
"object": "event",
"type": "vesting_overlay.executed",
"api_version": "2026-05-01",
"created": 1745262000,
"data": {
"object": {
"id": "vov_8aBcDeF1",
"object_type": "vesting_overlay",
"ledger_entry_id": "led_M8sNxK2f",
"grant_id": "grt_C1pT6yWh",
"authorizing_resolution_id": "res_LqGcSdRb",
"effective_date": "2026-05-01",
"tax_election_acknowledgement": { "decision": "file_new_83b" }
}
},
"sequence": 12,
"livemode": true,
"pending_webhooks": 1
}wind_down_reserve.*
DGCL §281(b)(iii) reserves set aside against disputed creditor claims during
a wind-down. Closely paired with creditor_claim.* — a reserve typically
opens when a claim disputes, and closes (released or fully paid) when the
claim resolves.
| Type | Description |
|---|---|
wind_down_reserve.opened | Reserve created; cash held against a specific CreditorClaim. |
wind_down_reserve.partially_released | Some held cash paid out via settlement or returned to residual pool. |
wind_down_reserve.closed | Terminal — claim resolved, all held cash disposed. |
{
"id": "evt_1Pq3Kw...",
"object": "event",
"type": "wind_down_reserve.opened",
"api_version": "2026-05-01",
"created": 1745263000,
"data": {
"object": {
"id": "wdr_9zYxWvU2",
"object_type": "wind_down_reserve",
"creditor_claim_id": "ccw_claim_42",
"creditor_claims_window_id": "ccw_8m3K2pLq",
"held_amount_usd": 75000,
"status": "held"
}
},
"sequence": 23,
"livemode": true,
"pending_webhooks": 1
}benefit_plan.*
Corporate-side governance + linkage events. Per the payroll-and-benefits handoff, Matter does not emit per-employee election events, premium remittance events, or 1099-R issuance events — those originate with the benefits administrator / record-keeper / carrier, not Matter. The events below cover plan existence, authorising governance, and termination state transitions.
| Type | Description |
|---|---|
benefit_plan.linked | Plan linkage record created — provider engaged, attestation Document captured. |
benefit_plan.administrator_designated | A plan_administrator_stakeholder_id set or replaced. |
benefit_plan.terminating | Termination Resolution executed; provider running the wind-down. |
benefit_plan.terminated | Provider acknowledgement Document received; plan terminal. |
{
"id": "evt_1Pq3Kx...",
"object": "event",
"type": "benefit_plan.terminating",
"api_version": "2026-05-01",
"created": 1745264000,
"data": {
"object": {
"id": "bp_5nMpQrSt",
"object_type": "benefit_plan",
"regime": "retirement_401k",
"provider_kind": "retirement_record_keeper",
"provider_name": "Guideline",
"termination_resolution_id": "res_LqGcSdRb",
"status": "terminating"
}
},
"sequence": 34,
"livemode": true,
"pending_webhooks": 1
}creditor_claim.*
Per-claim lifecycle within a CreditorClaimsWindow. Window-level events
(creditor_claims_window.opened / closed) live under the existing
entity.* namespace; this namespace covers the claim sub-state.
| Type | Description |
|---|---|
creditor_claim.recorded | Claim recorded against an open window. |
creditor_claim.disputed | Claim flipped to disputed; entity contesting amount or basis. |
creditor_claim.settled | Claim resolved via settlement Document. Carries settlement_payment_source. |
creditor_claim.denied | Claim denied; reason in payload. |
creditor_claim.time_barred | Window closed without resolution; claim time-barred per DGCL §281. |
mfn_cascade.*
The MFN cascade orchestrator fans out per-SAFE amendments and fans the
results back in. Each per-SAFE amendment also emits its own
document.generated / document.signed events on the amendment Document.
| Type | Description |
|---|---|
mfn_cascade.triggered | Orchestrator dispatched. Carries the trigger Round id and per-SAFE outcome counts. |
mfn_cascade.per_safe_amendment_sent | One eligible SAFE amendment dispatched to the holder. |
mfn_cascade.per_safe_skipped | One SAFE skipped (outside window, or no more-favourable terms). |
mfn_cascade.per_safe_rejected | Holder rejected the amendment. SAFE retains original terms; round still closes. |
mfn_cascade.per_safe_executed | Holder counter-signed; SAFE terms updated. |
mfn_cascade.completed | All per-SAFE outcomes resolved (signed, rejected, or skipped). |
{
"id": "evt_1Pq3Ky...",
"object": "event",
"type": "mfn_cascade.per_safe_rejected",
"api_version": "2026-05-01",
"created": 1745265000,
"data": {
"object": {
"id": "led_8n9PpkR3",
"object_type": "share_ledger_entry",
"trigger_round_id": "rnd_seed_2026",
"amendment_document_id": "doc_mfnAmend_001",
"rejection_recorded_at": 1745264998
}
},
"sequence": 45,
"livemode": true,
"pending_webhooks": 1
}webhook_endpoint.*
Meta-events about your endpoint itself.
| Type | Description |
|---|---|
webhook_endpoint.test_delivered | A POST /webhook_endpoints/{id}/test succeeded. |
{
"id": "evt_1Pq3Kl...",
"object": "event",
"type": "webhook_endpoint.test_delivered",
"api_version": "2026-05-01",
"created": 1745261000,
"data": {
"object": {
"id": "whe_2Lc3m4nO",
"object_type": "webhook_endpoint",
"url": "https://yoursite.example.com/webhooks/matter",
"tested_at": 1745260998,
"response_status": 200
}
},
"sequence": 1,
"livemode": false,
"pending_webhooks": 0
}Related
- Signing — verify the envelope before trusting the payload.
- Retries & replay — what happens if you don't 2xx in 30 seconds.
- Ordering — the per-entity invariants every event participates in.
- Events resource — fetch, list, expand individual events on demand.