Graph sends onboarding events to the webhooks configured for the organisation and environment that created the onboarding. Use data.id to find the onboarding in your system and data.event_id to deduplicate deliveries of the same event.
| Event | When Graph emits it | What to do |
|---|---|---|
entity_onboarding.created | Graph accepts a new onboarding. | Record its ID and associate it with your reference. |
entity_onboarding.updated | The public state or actions change on a nonterminal onboarding. | Fetch the onboarding to see what the applicant needs to do. |
entity_onboarding.completed | The person is ready and the onboarding is terminal. | Record data.person_id for subsequent requests in the same environment. |
entity_onboarding.failed | The onboarding reaches a terminal failure. | Inspect data.status_reason if present and stop polling this ID. |
Completion payload
The outer entity is entity_onboarding. The inner entity_type is person. In this example, data.id identifies the onboarding, while data.person_id identifies the resulting person.
{
"event_type": "entity_onboarding.completed",
"entity": "entity_onboarding",
"data": {
"id": "10000000-0000-4000-8000-000000000042",
"entity_type": "person",
"reference": "applicant-0042",
"status": "completed",
"status_reason": null,
"person_id": "30000000000040008000000000000042",
"created_at": "2026-11-01T12:00:00Z",
"updated_at": "2026-11-01T12:07:00Z",
"event_id": "40000000-0000-4000-8000-000000000042",
"occurred_at": "2026-11-01T12:07:00Z"
}
}
All four events include a snapshot with event_id and occurred_at. The reference and status reason can be null. The person ID is available on completion. Action URLs and identity documents are omitted. Fetch the onboarding with the same environment’s key to get its current state and available actions.
Acknowledge a handled event with an HTTP 2xx response. If the same event arrives again, use the saved event ID to avoid repeating work. You can also recover the current state by polling if a delivery is missed.