Webhooks

Introduction

Gusto Embedded offers webhooks for Partners to receive Webhook Events events.

A Partner can register a webhook subscription URL and a list of subscription types to receive updates for every PartnerManagedCompany. After verifying the subscription, Partners receive webhook notifications events as entities are created or modified.

Creating a webhook subscription

An API Token is required for all webhook subscription requests.

Creating a webhook subscription requires a callback URL and subscription_types. The URL will receive POST requests from Gusto. The provided subscription_types map to Gusto Embedded entities.

Example: if Employee is included as a subscription_type, when partner managed company employees are created or modified, the callback URL will receive POST notification events comprised of the associated employee represented as JSON.

Verifying subscription

Before the subscription URL will gets sent entity event updates, it will first receive a verification_token of the form

{"verification_token": "6590f590-3dba-495e-9bea-c361e1e2efc0"}

The subscriber received verification_token must be verified.

This ensures that the creator of the webhook subscription controls the registered subscription URL.

Handle requests

Handle requests by Gusto by parsing each Webhook Event ](JSON) and returning 2XX response status codes. If the returned response status code is not 2XX, Gusto will retry the request up to 16 times with an exponential backoff.

Verifying event integrity

Gusto computes a hash message authenticate code (HMAC) of the event payload using the verification_code as the secret and SHA256 as the hash function. Webhook Events include a x_gusto_signature header, which is set to the computed HMAC.

Event payload integrity can be verified by the subscriber by computing the event payload HMAC and checking that it is equal to the HMAC in the x_gusto_signature header.

previously_received_verification_token = '6590f590-3dba-495e-9bea-c361e1e2efc0'

hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('SHA256'),
                                    previously_received_verification_token,
                                    r.body.read)

if hmac == r.env['HTTP_X_GUSTO_SIGNATURE']
    puts "the event was sent by Gusto"
else
    puts 'do not trust the source'
end