--- url: /software_partners/build/webhooks/list_of_webhooks.md --- # List of webhooks This document contains information about the list of webhooks that are emitted from SuperAPI. You can use this reference to find out: 1. When and why a webhook is emitted 2. The contents of that webhook. We will also go into some detail about some hypothetical actions you might want to take in the system upon receiving a particular webhook. ## Understanding SuperAPI webhooks ### The subject Webhooks are always based on a subject entity in our system. Currently, these subject entities are an `employer`, an `onboarding_session`, an `onboarding_session_intent`, or an `employer_issue`, but we may extend this to more entities depending on the nature of the webhook. For example, if we were to emit a webhook related to an event occurring with a product in our system, then the subject of that webhook would be a `product`. You can also think of the webhook subject being a kind of namespace for the webhook. ::: warning We may introduce additional webhook namespaces for `employee` and `product` in the future. ::: ### The event Webhooks are sent based on events occurring in our system, and this information is also passed to the consumer of the webhook. Events include things like an employer changing their settings or an onboarding session being completed. ### The payload Webhooks contain a minimal payload designed to give you enough information to be able to make a request to our API to fetch further information. All webhooks follow a similar structure; an example being: ```json { "subject": "employer", "event": "employer_settings_changed", "id": "c2bc0c04-6b98-4333-91a6-919f5ebc9000", "remote_id": "1234", "url": "https://api.superapi.com.au/api/v1/employers/c2bc0c04-6b98-4333-91a6-919f5ebc9000", "product_id": "8f14e45f-ceea-467e-951e-93fa5ec8f4c0", "inserted_at": "2025-06-09T03:21:00Z", "version": "1" } ``` | field | kind | description | | ---------- | ------ | ------------------------------------------------------------------------------------------------ | | subject | string | The entity that the webhook belongs to | | event | string | The event in our system that triggered the webhook | | id | string | The primary key of the entity that triggered the webhook | | remote\_id | string | The remote\_id of this entity in your system | | url | string | The URL you should call to fetch the entity that triggered the event | | product\_id | string | The product this event belongs to. Use it to pick the Product API Key to call `url` with | | inserted\_at | string | When the webhook was generated (ISO 8601) | | version | string | Payload version | ## Webhooks list ### Employers | Name | Fired when | Notes | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | employer\_settings\_changed | An employer has changed settings that are relevant to our partner, e.g., they have picked a default fund or their stapling status has changed | You should fetch the employer object from SuperAPI and check if it is now correctly configured to allow onboarding sessions to be created. | ### Onboarding sessions | Name | Fired when | Notes | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | onboarding\_session\_changed | An employee has made progress through the onboarding session | Fired when the employee has made progress through the onboarding session. Useful for showing the progress of the user through the onboarding session, e.g., on a dashboard. Can also be used to populate details into systems before the onboarding session has been completed. For example, payroll details could be populated early by listening to this webhook then updated again once the final webhook has been sent. See [Syncing data to third party systems](/software_partners/build/webhooks/sync_data_to_third_party_systems/index.html) for a worked example of this pattern. Also fires when the super choice form PDF becomes available, shortly after the member confirms their fund choice. | | onboarding\_session\_completed | An employee has completed an onboarding session | Fired at the completion of the onboarding session. This will contain all information gathered about the employee, including any long running processes (e.g., register a member via an MRR). No more webhooks will be sent after this. | ### Onboarding session intents An onboarding session intent is the record created when an employer starts onboarding an employee from the intent embed, before a full onboarding session exists. See [Onboarding session intents](/software_partners/build/onboarding_sessions/intents/index.html) for the full flow. | Name | Fired when | Notes | | --------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | onboarding\_intent\_completed | The employer has finished the intent embed and the intent is now `complete` | Fetch the intent from `url`, then create the onboarding session from it with `POST /api/v1/onboarding-session-intent/{id}/onboarding-session`. Track that session through the onboarding session webhooks above. | ### Employer issues Employer issue webhooks are off by default — ask your SuperAPI contact to enable them for your partner account. See [Respond to employer issues](/software_partners/operate/respond_to_employer_issues/index.html) for the full workflow. For this subject, the `remote_id` field mirrors `id` (issues have no partner-supplied remote id). | Name | Fired when | Notes | | ----------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | employer\_issue\_created | A new partner-actionable issue has been opened for one of your employers | Fetch the issue from `/api/v1/employer-issue/{id}` to read its `kind` and `recommended_actions`, then surface it to the employer (e.g. an email or a support ticket). The `id` is a stable idempotency key. | | employer\_issue\_resolved | An open issue was **automatically** resolved (e.g. the employee onboarded and now has a valid fund membership) | Use this to clear any notification you raised for the issue. Not fired when you resolve an issue yourself via `PUT /api/v1/employer-issue/{id}/resolve` — clear your notification in that code path instead. |