A leap towards self-service
Our Embedded Payroll partners want to build robust payroll products that are reliable, performant, and accurate. Building an embedded payroll application is no small feat. We want to embrace any opportunity to accelerate that development process.
As we continue to work with new and existing partners, we have seen that there is a great opportunity to build self-service tooling to speed up the development process. In addition to our API and our pre-built UI (Flows), we also provide a developer portal to help partner developers get up and running.
I started at Gusto earlier this year. One of my first tasks was to “dogfood” the developer portal and provide feedback given my newbie perspective. It’s a tool that currently supports registering new OAuth applications, fetching API credentials, and creating demo companies, all of which allow partners to make their first API calls. In my exploration, it was clear that there was enormous potential to expand upon the current features and make it a more powerful tool. In fact, some exciting feature work was already underway, and as my first project at Gusto, I was able to contribute to that work.
Turning challenges into opportunities
To inform the development of our first self-service features, we turned to our trusted Technical Solutions team. We wanted to learn about partner pain points, and they were the perfect source for first-hand information.
In talking to them, webhooks came up as a common theme. At the time, setting up and testing webhooks was both tedious and confusing. For partners to test notification payloads, our Technical Solutions team had to manually trigger different notifications for them. Additionally, the team was receiving webhook troubleshooting requests that often had simple fixes. Sometimes, the subscription was simply unverified, or there was a spelling error in the URL, or our notification attempts failed because the endpoint would not return a successful 200 status code. In essence, there was a lack of visibility into the different points of failure.
These challenges with webhooks provided a great opportunity to kick off our self-service vision for the Developer Portal. Setting up the right webhooks tooling would both relieve our Technical Solutions team from inefficient workflows and remove a major point of friction for our partners.
Why leverage webhooks?
Because our partners are building embedded payroll solutions, there is a need for a real-time feedback mechanism between Gusto and partner applications so that they can serve their customers quickly and accurately.
Let’s use the company onboarding process as an example. Before an employer can run its first payroll through a partner, the company needs to be onboarded onto Gusto’s platform. This process involves several steps. Once a company’s onboarding is complete, Gusto will underwrite the company as part of our risk-analysis process and approve or reject that company. A company cannot run payroll until it has been approved.
As you can imagine, this is a time-sensitive process. Our partner applications need to know whether a company has been approved or rejected ASAP so they can alert employers about the proper next steps. In other words, they need real-time updates about the approval status.
So, how does the partner application know when the company has been approved? One option is by polling our Company API. The partner application can periodically send a request to our GET /v1/companies/:company_id endpoint. Eventually, they will receive a response where the company_status for their company is either Approved or Rejected. This might be fine for a few companies, but this is not a tenable solution at scale.
This is where webhooks can be powerful. Instead of constantly pinging our API for status updates, the partner application can passively wait until we notify them of an approval. By setting up a webhook subscription with a “Company” subscription type, they can be alerted for any of the available Company events. Now, imagine the time and resource savings for each event in the 19 subscription types we currently support.
How do you set webhooks up?
In the background, Gusto constantly produces events, independent of webhook subscriptions. You can fetch those using our /v1/events API. If you want your application to be notified about specific event categories (or, subscription types), this is where setting up a webhook subscription comes in handy. The events that your subscription receives are a subset of all the events we produce, and you can always update which types your subscription is listening to.
Historically, the way to set up webhook subscriptions has been through the Gusto API. As a developer, you’d have to use cURL or Postman to create, verify, edit, or delete a subscription through our webhooks endpoints. Setting this up can be a little clunky.
As a developer, I had the chance to put myself in the shoes of our partner developers. In my own setup, I experienced first-hand some of the questions that our Technical Solutions team received: How do I know if my subscription is working? Why am I not seeing any events yet? What do the event payloads look like? Is there an easy way to test them? Wait, there’s a verification step? What if I don’t receive an event I was expecting?
It’s a unique opportunity to experience the same challenges as your users. With these direct experiences in mind, we set out to build our newest Developer Portal features.
Webhooks in the Developer Portal
A few months ago, we launched our Test Notifications feature in the Developer Portal, which is available for Demo applications. Shortly after, we released our Webhook Subscription management feature (for both Demo and Production applications). Together, these 2 tabs work in tandem to make managing and testing webhooks with Gusto Embedded intuitive and fast.
Now, a partner can choose from a list of over 35 different notifications to test.
With the Webhook subscriptions tab, developers can easily view all their subscriptions, see their statuses, verify any unverified subscriptions, and quickly edit them to quickly update which subscription types to consume.
Developers can now also gain further insight into the notifications each subscription receives. Below each subscription, we expose a stream of recent events to that subscription, how many attempts were made, whether any of those attempts were successful, and further details by event. There is also a search feature to filter down events by event type.
Looking Forward
As developers developing for other developers, we have the unique opportunity to experience firsthand pain points in our development process. We look forward to digging deeper into the usage patterns of our partner developers and expanding our “self-service” vision for the Developer Portal.
