Partner Notifications

An effective payroll solution requires clear and compliant communication with customers for critical processes such as onboarding, payroll processings, and tax filings. For compliance reasons, customers need to be notified in several scenarios (including, but not limited to):

• The payroll provider requires additional information (e.g. documents to finish onboarding, bank screenshots to expedite payroll)
• The customer has a key deadline to meet (e.g. deadline to run payroll, deadline to make changes for filings)
• A payroll has been blocked and cannot be processed (e.g. customer is in collections from a previous payroll)
• An employee or contractor has open onboarding tasks (e.g. W4 form must be signed)

Building critical notifications

We provide notification webhook events, as well as the v1/events API endpoint, to empower you to fully own and manage critical notifications with end users in your product. That allows you to send notifications in the method you prefer - whether it be through an in-app notification, SMS, or partner-branded email.

There are two options to integrate with our notification system:

Option 1: Subscribe to notification webhook events

Each notification has a category. These can be identified by the event_type attribute in the webhook event payload.

If you already have a webhooks integration with us, you may update your subscription to include the Notification entity and start receiving these events.

📘

What's different about a Notification webhook event?

Notification webhook events signify that a critical communication must be relayed to an end user. As we plan to stop sending emails from Gusto.com to your end users, we recommend that you utilize our new notification system to manage and send these critical communications.

Other webhook event types indicate that an entity has been created, updated, or deleted, and enables you to perform subsequent processing logic in your application.

Option 2: Leverage our Events API

We also enable you to poll our webhook events using our v1/events endpoint, so that you can filter and fetch all webhook events that your application has the required scopes for.

Note that this may potentially include other webhook events outside of notifications, and a partner does not have to verified webhook subscriptions in order to utilize this endpoint.

Once notified, we recommend that you use the notification_uuid from the event payload to fetch additional notification details via our new API endpoint: GET v1/notifications/:uuid. In this API response, we provide suggested copy (title and message) that you may reuse or adapt when building and sending critical notifications to your customers.

📘

Note that notifications are read-only.

Our system will handle changing the status of a notification from open to resolved once the relevant actionable item has been completed. We will also publish a notification.*.resolved webhook event.

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 each new notification we plan to keep both emails and notification webhook events enabled to ensure a smooth transition. We will notify you in advance about which emails we plan to deprecate, and when, in order to allow sufficient time for you to integrate with this new partner notification system. A schedule of this migration process and the date each email will be deprecated is published here, and will be regularly updated.