Event catalog

This page lists every event yggy sends, when it is sent and what its payload holds. All events share one envelope, and the sections below explain the graph change and connection health events in more detail. To receive them, set up an endpoint first.

Events

Event	Sent when
document.uploaded	A document was accepted for processing: an upload, a provider import, a bulk ingest, a yggy notes attachment or a re-import.
document.processed	A document finished processing. A bulk ingest sends it for each document when the ingest completes.
document.failed	Processing failed or was cancelled.
document.deleted	A document was deleted.
review.item_created	A review item entered the inbox: an ontology proposal, an identity mapping, a possible duplicate entity or two facts that contradict each other. An item that was kept apart and is detected again comes back with reopened: true.
review.item_resolved	A review item was accepted, discarded or undone, by a person, an AI assistant or yggy automatically. It is sent once per real change; repeating the same decision sends nothing.
connection.sync_completed	A connection finished a sync that changed at least one item. A sync that found nothing new sends no event.
connection.sync_failed	A connection’s last 3 syncs failed in a row. Sent once per run of failures; it can come again only after a sync worked or the connection was reconnected. See Connection health.
connection.auth_expired	yggy lost access to a connection: the account removed access, or the sign-in no longer works. Sent once; the connection stays this way until someone reconnects it. See Connection health.
graph.entities_changed	Entities were created, updated or deleted. Sent about once a minute per organization; see Graph changes.

Payloads carry ids and a few descriptive fields, such as a document title. They never contain document content, extracted text or entity values. A payload is at most 64 KB, and yggy does not send an event that would be larger. Use the ids with the REST API to read more.

Every request has the same envelope:

{
  "id": "evt_4f9a0c1e-7b2d-4c35-9a51-2f6e8d1c0b7a",
  "type": "document.processed",
  "created_at": "2026-10-12T12:04:12.311Z",
  "organization_id": "org_7Hq2",
  "data": {
    "document": { "id": "9b1e...", "project_id": "acme-default", "title": "Q3 report.pdf", "status": "COMPLETED" },
    "triple_count": 128
  }
}

The data object per event:

Event	data
document.uploaded	{ "document": { "id", "project_id", "title", "status" } }
document.processed	{ "document": {...}, "triple_count": 128 }
document.failed	{ "document": {...}, "reason": "failed" }, or "cancelled"
document.deleted	{ "document": {...} }
review.item_created	{ "item": { "kind", "id", "project_id", "document_id" }, "reopened": false }. kind is ontology_proposal, identity_claim, entity_merge (a possible duplicate entity) or triple_conflict (two facts that contradict each other). reopened is true when the item came back to the inbox after it was kept apart.
review.item_resolved	{ "item": { "kind", "id", "project_id" }, "resolution": "accepted", "actor": "user" }. resolution is accepted, discarded or undone; actor is user, agent (an AI assistant) or automatic. For a merge of several entities, id is the entity the others were merged into; otherwise it is the review item’s id.
connection.sync_completed	{ "connection": { "id", "type" }, "items_changed": 3 }
connection.sync_failed	{ "connection": { "id", "type" }, "failures": 3, "failing_since": "2026-10-12T09:40:00.000Z", "error": "rate_limited" }. failing_since is when the first of the failed syncs happened. error is provider_error, rate_limited or network.
connection.auth_expired	{ "connection": { "id", "type" }, "reason": "grant_revoked" }. reason is grant_revoked or unauthorized.
graph.entities_changed	{ "created": ["0x1a2b"], "updated": [], "deleted": ["0x3c4d"], "truncated": false }
webhook.test	{}

The OpenAPI document lists each shape as a WebhookEvent* schema.

Graph changes

graph.entities_changed tells you which entities changed, so you can keep a copy of your organization’s entities current without polling:

• yggy collects changes and sends one event about once a minute per organization, with three lists of entity ids: created, updated and deleted. The ids are the entity id that the graph endpoints of the REST API return and accept. The event carries no names or values.
• An id is in at most one list. The newer change wins, except that an update never replaces a create or a delete. An entity created and deleted within the same window is only in deleted. An entity that was merged away and split off again within the window is in created.
• A merge lists the entity that remains in updated (or in created, when the merge made a new entity) and the entities merged into it in deleted. A split lists the restored entity in created.
• Each list holds at most 1000 ids, and yggy shortens the lists further when the event would otherwise be over 64 KB. When ids were left out, or more changes are waiting, truncated is true: read the current state from the API instead of relying on the lists. The changes that were waiting come in the next event.
• Delivery is at least once, so an id can arrive again in a later event. Events can also arrive out of order, so when you see an id in a different list than before, read the entity from the API.
• The event covers entities that processing a document creates or updates, and merges, splits, renames, retypes and deletes, whether a person, an AI assistant or yggy made them. Entities an AI assistant adds directly, changes to single facts, and identity updates yggy makes on its own are not listed.

Connection health

yggy watches the syncs of some connection types and tells you when one needs attention:

• Sync health is recorded for Google Drive and for Gmail and Outlook calendar syncs. Lost access is detected when yggy renews a connection’s sign-in, and when Google Drive refuses a sync. Other connection types send no health events yet.
• When a connection’s last 3 syncs failed in a row, yggy sends connection.sync_failed once for that run of failures. A failing connection keeps working: yggy keeps syncing it on the usual schedule, and browsing and importing from it still work. The first sync that works, or a reconnect, ends the run and sends no event of its own; connection.sync_completed still arrives when a sync changed something. If syncs start failing again later, a new run can send a new connection.sync_failed.
• Only problems with the provider count: the provider refusing requests or answering with an error, rate limiting yggy, or not being reachable. error says which of these it was. Problems on yggy’s side never count, and neither does a single file yggy cannot read, such as a Google Drive file whose download was turned off: yggy skips that file and syncs the rest.
• When yggy loses access to a connection, it sends connection.auth_expired once. grant_revoked means the account removed yggy’s access or the sign-in ran out. unauthorized means the provider refused a sign-in that should still work. Only a connection in this state stops syncing, until someone reconnects it under Data Sources. After the reconnect, a later loss of access sends a new event.
• Connections are named by id and type only, also for a member’s personal connection. No event carries the provider’s own error message.