Partner Notifications

In order for our Embedded Payroll partners to communicate with employers, employees, signatories, and contractors, Gusto Embedded has launched our Partner Notification System. A combination of webhook events and a Notification endpoint that will allow partners to be informed of key payroll events which they can then pass along to their users.

The Partner Notification System will allow partners to customize their end communication as they see fit. Notifications will be categorized, will include message titles and copy, will indicate whether or not the action is required, and will inform if payroll is blocked until the action is taken. Text messages, emails, and dashboard banners can all be built on top of the Notification System to ensure customers are made aware of critical items and take the steps necessary to focus on getting people paid correctly and on time.

1. Subscribe to webhook events

The first step in utilizing the Notification System will be to subscribe to the notifications webhook events. Each notification event will follow this general format:

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

The webhook notification events will be triggered when a notification is created, when a notification expires, and when the notification has been resolved. The .resolved or .expired event 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 (more to come later).

📘

Events endpoint

If you miss a webhook notification event, you can use the “get-events” endpoint. This endpoint can pull all webhook events by company, or you can use it to grab a single webhook event.

That said, all partners should be leveraging our webhook events for their payroll build. We do not recommend relying solely on the "get-events" endpoint because events are removed after 30 days, so only use this endpoint as a failsafe.

2. Call the Notification endpoint

Using the notification ID, call the notification endpoint to build out your end customer communication. Each notification will information including the following:

• The company UUID
• The category (mirrors the category in the webhook event)
• The title of the notification
• The message with additional context
• Boolean for actionable (is there an action that needs to be performed by an individual at the company?)

There are three types of notifications you will see:

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

Informational

For this use case, there is no specific action requested of the user but the information has been identified as valuable to pass along to the intended user.

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

1. Notification is created when forms are available:

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

2. Then using the Notification entity_uuid from the above notification webhook event, make a request to the notifications endpoint, which will return additional information:

{
  "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",
  "actionable": false,
  "can_block_payroll": false,
  "published_at": "2022-01-01T00:00:00.000Z",
  "due_at": "2022-01-09T00:00:00.000Z",
  "status": "open",
  "template_variables": {
    "quarter": 1
  },
  "resources": [
    {
      "entity_type": "Employee",
      "entity_uuid": "98a85b2-3ab1-55ed-24d3-abc80303d788"
    }
  ]
}

3. With the information from that response a partner can pass along the information to the end user(s). This could be done via email, text, dashboard notification, etc. If a notification is relevant to specific employees or contractors, their UUIDs will be included in the resources array in the notification payload. This can be useful in determining who to notify about a particular notification. In addition, depending on the notification, other relevant UUIDs may also be included – like the UUID of an affected bank account or payroll. This can be used to provide further supplemental information.
4. If the notification has a defined expiration point, a webhook event will come back like this**

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

5. As an optional step, you could relay the expiration to the end user (ex. dismiss a dashboard banner).

**Since Gusto is unable to verify the receipt of this message to the end customer we won’t automatically close the notification out. In certain situations, the notification will change to “expired” if Gusto can guarantee that the notification is no longer applicable to a user. This table indicates which informational-only notifications remain open and which notifications expire.

Actionable to be closed out in partner platform

In the second use case, similar to informational notifications, they will not auto-change to a “resolved” state, but they do require an action be performed by the user. These notifications stay in an “open” state or may expire.

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

1. Notification is created when Gusto detects an error with an employee's personal information.

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

2. Using that Notification Entity ID from the notification webhook, make the API call to the notifications endpoint:

{
  "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",
  "actionable": true,
  "can_block_payroll": true,
  "published_at": "2022-01-01T00:00:00.000Z",
  "due_at": "2022-01-09T00:00:00.000Z",
  "status": "open",
  "template_variables": {
    "person_name": "%{person_full_name}",
    "href": "%{link}"
  },
  "resources": [
    {
      "entity_type": "Contractor",
      "entity_uuid": "12385b2-44b1-5598-ffdf-e1180223d78d"
    }
  ]
}

3. With the information from that response, the partner can pass along the information to the end user(s). This could be done via email, text, dashboard notification, etc. The UUID of the person with the invalid tax info is listed in the resources array in the notification, which can be used to determine who needs to be notified. The partner can also include guidance with links to the Social Security Administration website on what information is needed for validation.
4. The notification will stay open, but since the communication has been sent, there is no further job for the partner, if the notification expires, a subsequent webhook would come through.

Actionable and Gusto-resolved:

In the final use case, when notifications involve specific Gusto action, they will automatically resolve once the action has been confirmed and completed on the Gusto end.

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 for when the payroll goes into recovery:

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

2. Using that Notification Entity ID from the notification webhook, make the API call to the notifications endpoint:

{
  "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",
  "actionable": true,
  "can_block_payroll": true,
  "published_at": "2022-01-01T00:00:00.000Z",
  "due_at": "2022-01-09T00:00:00.000Z",
  "status": "open",
  "template_variables": {
    "event_date": "Monday Jan 1",
    "event": "%{event}",
    "case_id": 12345
  },
  "resources": [
    {
      "entity_type": "RecoveryCase",
      "entity_uuid": "975abe-ba38-1147-bbac-12380223ffef"
    }
  ]
}

3. In order to then re-trigger the debit for the payroll and pay the team on time for the next payroll, the partner can pass along the message to the user and can generate a pre-built Gusto designed flow where we show all recovery cases and how to resolve them:

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
}

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

There are several different notifications in which GEP provides accompanying flows to help resolve, including:

• Request for Information
• Invalid Signatory
• Recovery Cases

Deprecating Gusto.com emails

As part of this project, we will be sequentially deprecating Gusto.com branded emails from being sent directly to company payroll admins, and replacing them with a new notification category. This rollout will happen in prioritized batches.

At the initial rollout of notifications we plan to keep both emails and notification webhook events enabled to ensure a smooth transition. We will notify you in advance about when we plan to deprecate emails in order to allow sufficient time for you to integrate with this new partner notification system.

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. There are also notifications that are not set to expire or resolve on the GEP side; that tracking needs to be done on the Embedded Partner side.

Can I resolve notifications myself?

No, this is a read-only endpoint and notifications that are resolved only come with certain notifications based on the nature of the notification. For a break down of the treatment of each notification more detail can be found here.

I thought GEP sent emails to users, is that still the case?

We are in the process of deprecating all direct email notifications to end customers given the inflexibility in copy and the clear Gusto branding (the emails are intended for Gusto.com users and not Gusto Embedded). For all current partners we will be providing a grace period to switch over to the new email system in the future. During this overlap in development, you may receive both a webhook notification and Gusto branded email for the same use case.

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.