Partner notifications

Gusto Embedded partners can deliver timely and relevant communication to employers, employees, signatories, and contractors with the Partner Notification system. This system includes webhook events and a notifications endpoint that partners can use to power their own user-facing messaging, such as emails, text alerts, or dashboard banners.

Notifications include a message title, category, actionability status, and whether the issue blocks payroll. Partners can use this data to inform end users of critical payroll-related events. See the Partner Notification Types guide to learn more about supported notification types.

Set up notifications

1. Create a webhook subscription

Follow the Getting Started instructions in our Webhooks guide to set up and verify a webhook subscription, and then come back to this guide to move on to the next step.

2. Subscribe to Notification webhook events

Start by subscribing to Notification webhook events, which are triggered when a notification is created, resolved, or expired.

Notification webhook payloads follow this structure:

{  
  "uuid": "dd929277-ad89-4e8b-bb8b-cfd229b05b9a",
  "event_type": "notification.information_request.created",  
  "resource_type": "Company",  
  "resource_uuid": "f6a168b4-487d-4688-8812-911c86803b57",  
  "entity_type": "Notification",  
  "entity_uuid": "86e785b3-37a1-40ed-94e4-3cedd3f2fc90",  
  "timestamp": 1688587457  
}

Here are the types of notification webhook events, and when they are triggered:

The .resolved and .expired events will have the same title and message as the original notification event.

It is important to note that not all notifications will resolve or expire: If the notification is informational only, it can be left open indefinitely.

📘

Missed a webhook?

You can use the /v1/events endpoint to retrieve missed events. Events are only stored for 30 days however, so you should leverage webhook events for your payroll build instead of relying on this endpoint.

3. Call the notification endpoint

Using the entity_uuid from the webhook, call the /v1/notifications/{notification_uuid} endpoint to retrieve detailed information that you can use to build your end-customer communication.

Each notification will fall into one of three categories:

• Informational
• Actionable to be closed out in the partner platform
• Actionable and Gusto resolved

📘

Each response includes details such as company ID, status, title, message, due date, and references to related resources, including employees or payrolls. Some notifications include timestamps for publishing or expiration.

Informational

No action required. These messages are often identified as valuable to pass along to the intended user and typically relate to completed tasks, such as filings or payroll events. Some expire, others remain open.

An example would be if tax forms had been filed. The implementation would look like this:

1. A notification is created when forms are available:

{
  "title": "Tax Forms are now available for Q1",
  "message": "Filings were submitted successfully and are now available.",
  "category": "end_of_quarter_payroll_filings",
  "actionable": false,
  "can_block_payroll": false,
  "published_at": "2022-01-01T00:00:00.000Z",
  "due_at": "2022-01-09T00:00:00.000Z"
}

2. Using the entity_uuid from the Notification webhook, call /v1/notifications/{notification_uuid} to receive a response like the following:
   JSON

   {
     "uuid": "86e785b3-37a1-40ed-94e4-3cedd3f2fc90",
     "company_uuid": "88f7cca1-dcad-4d20-84db-7fb80303d69f",
     "title": "Tax Forms are now available for %[Quarter] for Review",
     "message": "Filings were submitted successfully and are now available.",
     "category": "end_of_quarter_payroll_filings",
     "status": "open",
     "actionable": false,
     "can_block_payroll": false,
     "published_at": "2022-01-01T00:00:00.000Z",
     "due_at": "2022-01-09T00:00:00.000Z",
     "template_variables": {
       "quarter": 1
     },
     "resources": [
       {
         "entity_type": "Employee",
         "entity_uuid": "98a85b2-3ab1-55ed-24d3-abc80303d788"
       }
     ]
   }
   

Actionable (resolved in partner platform)

These require user action and remain open until resolved in your system. Gusto does not auto-resolve them.

An example would be incorrect employee information input (birth date, legal name, or social security number):

1. A notification is created when Gusto detects an error with an employee's personal information:
   JSON

   {
     "title": "Action required: Update Jane Doe's tax info",
     "message": "This employee's information doesn't match SSA records. Please update.",
     "category": "invalid_ssn",
     "actionable": true,
     "can_block_payroll": true
   }
   

2. Using the entity_uuid from the Notification webhook, call /v1/notifications/{notification_uuid} to receive a response like the following:
   JSON

   {
     "uuid": "99998888888",
     "company_uuid": "88f7cca1-dcad-4d20-84db-7fb80303d69f",
     "title": "Action required: Update %{person_full_name}'s tax info",
     "message": "This employee's information doesn't match what's on file with the Social Security agency. Fixing this will help make sure tax filings go smoothly.",
     "category": "invalid_ssn",
     "status": "open",
     "actionable": true,
     "can_block_payroll": true,
     "published_at": "2022-01-01T00:00:00.000Z",
     "due_at": "2022-01-09T00:00:00.000Z",
     "template_variables": {
       "person_name": "%{person_full_name}",
       "href": "%{link}"
     },
     "resources": [
       {
         "entity_type": "Contractor",
         "entity_uuid": "12385b2-44b1-5598-ffdf-e1180223d78d"
       }
     ]
   }
   

3. The partner identifies the affected user using the UUID from the resources array in the notification and sends a message via email, text, or dashboard. This message can include guidance and a link to the Social Security Administration website.
4. After the message is sent, the partner does not need further action. If the notification expires, a new webhook will be sent.

Actionable (Gusto-resolved)

These require action, but are automatically resolved once Gusto verifies the issue is handled.

An example of this notification would be when a company goes into recovery because it defaulted on a faster payroll:

1. A notification is created when the payroll goes into recovery:
   JSON

   {
     "title": "Action required: Unfreeze bank account to unblock payroll",
     "message": "We couldn't debit funds for payroll. Unfreeze the bank account.",
     "category": "recovery_case.unfreeze_bank_account",
     "actionable": true,
     "can_block_payroll": true
   }
   

2. Using the entity_uuid from the Notification webhook, call /v1/notifications/{notification_uuid} to receive a response like the following:
   JSON

   {
     "uuid": "0009",
     "company_uuid": "88f7cca1-dcad-4d20-84db-7fb80303d69f",
     "title": "Action required: Unfreeze bank account to unblock payroll",
     "message": "We weren't able to debit funds for the %{date} %{event}. To pay the team on time, unfreeze the associated bank account as soon as possible.",
     "category": "recovery_case.unfreeze_bank_account",
     "status": "open",
     "actionable": true,
     "can_block_payroll": true,
     "published_at": "2022-01-01T00:00:00.000Z",
     "due_at": "2022-01-09T00:00:00.000Z",
     "template_variables": {
       "event_date": "Monday Jan 1",
       "event": "%{event}",
       "case_id": 12345
     },
     "resources": [
       {
         "entity_type": "RecoveryCase",
         "entity_uuid": "975abe-ba38-1147-bbac-12380223ffef"
       }
     ]
   }
   

3. To re-trigger the payroll debit and ensure the team is paid on time, the partner can forward the message to the user and present a pre-built Gusto-designed flow that displays all recovery cases and guidance on resolving each one.

4. Once that case has been resolved, we will send a notification event indicating the action was resolved:

{
  "uuid": "dd929277-ad89-4e8b-bb8b-cfd229b05b9a",
  "event_type": "notification.recovery_case.unfreeze_bank_account.resolved",
  "resource_type": "Company",
  "resource_uuid": "f6a168b4-487d-4688-8812-911c86803b57",
  "entity_type": "Notification",
  "entity_uuid": "0009",
  "timestamp": 1688587457
}

The partner can then choose to pass along the state of resolution or ignore and let the customer continue with processing payroll.

Test your notification integration

To confirm that your notification implementation works correctly, use the self-serve notification testing tool in the Developer Portal. This is available in the Demo environment.

This tool lets you trigger notification webhooks to your application's webhook URL. You can also verify events by calling the /v1/events endpoint. To configure your webhook listener, follow the Webhooks guide.

🚧

This tool will identify or create a company with the appropriate conditions to meet the notification scenario; in other words, it's not possible to create a notification for a specific company using this tool.

1. Trigger a test notification

1. Sign in to the Developer Portal.

   

2. Under your partner application, select the Test notifications tab.

3. Select the notification category you want to test. For a list of all partner notification categories, see the Partner notification types guide.

   📘

   Some notification categories aren't available for self-serve testing in Demo. Contact your technical solutions representative if you need help triggering an unsupported category.

4. Click Submit.

5. If webhook subscriptions are set up correctly, your URL should receive an event for the selected category. Webhook delivery may take a few minutes to complete. You can also poll /v1/events by event_type to confirm receipt.

2. Retrieve the test notification

When triggered, notifications are applied to a demo company configured on your behalf. These companies are prefixed with [Demo notification testing]. It’s not possible to create a notification for a specific company using this tool.

To view the notification:

1. Copy the company_uuid from the webhook payload.
2. Go to the Demo Companies tab in the Developer Portal.

   📘

   We provision and manage demo companies for notification testing. Some notifications cannot be added to companies with blockers, so we may provision multiple demo companies.

3. Locate the company using the UUID.
4. Click Show tokens.
5. Use the token to call the /v1/notifications/{notification_uuid} endpoint.

For actionable notifications with resolution events, confirm you receive the .resolved event after the item is completed.

Example: Test end-to-end in your app

To simulate an information_request notification:

1. Select the information_request category in Developer Portal > Test notifications tab.
2. When your app receives the notification.information_request.created event, call the /v1/notifications/{notification_uuid} endpoint.
3. Build the notification in your UI with a call-to-action linking to the company_information_requests flow.
4. After submission, expect to receive a notification.information_request.resolved event.

FAQ

Should I store notification information like events and information on my end?

Yes! This is the best path to tracking the paper trail of communication with your customers.

In addition, some notifications do not expire or auto-resolve, so that tracking must be done on the Embedded Partner side.

Can I resolve notifications myself?

No. Resolution is controlled by Gusto, and the notifications that come from resolution depend on the notification type.

Read more about the resolution, if applicable, of different notification types, see the Partner notification types guide.

How do I test these notifications?

The trigger points themselves will occur at the logical points in which we’d create a notification, ex. If an RFI is created then a notification will come through. For help with testing please reach out to your TS representative for more assistance.

Will Embedded be adding more notification categories in the future?

Yes, we’ll add and refine notifications over time as we identify improvements.