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, 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:

{
  "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"
}

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

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 for a worked example of this pattern.
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.

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 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.