Webhooks

Gusto Embedded offers webhooks for Partners to receive Webhook Events.

1. Create a webhook subscription

You can register a webhook subscription URL using the POST webhook_subscriptions endpoint and a list of subscription types.

curl --request POST \
     --url https://api.gusto-demo.com/v1/webhook_subscriptions \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "subscription_types": [
          "Company",
          "Employee"
     ],
     "url": "https://leading-role-app.com/subscriber"
}
'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/webhook_subscriptions';
const options = {
  method: 'POST',
  headers: {accept: 'application/json', 'content-type': 'application/json'},
  body: JSON.stringify({
    subscription_types: ['Company', 'Employee'],
    url: 'https://leading-role-app.com/subscriber'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

2. Verify the Subscription

Before the subscription URL receives any event updates, it will first receive a verification_token .

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

Use this token with the PUT webhook_subscriptions/{webhook_subscription_uuid}/verify endpoint to verify the endpoint and begin receiving webhook events.

curl --request PUT \
     --url https://api.gusto-demo.com/v1/webhook_subscriptions/{webhook_subscription_uuid}/verify \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "verification_token": "asefasedfe23e234easd"
}
'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/webhook_subscriptions/{webhook_subscription_uuid}/verify';
const options = {
  method: 'PUT',
  headers: {accept: 'application/json', 'content-type': 'application/json'},
  body: JSON.stringify({verification_token: 'asefasedfe23e234easd'})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

3. Handle Requests

Our systems expects you to return a 2XX Status Code when you receive the webhook. If the returned response status code is not 2XX, Gusto will retry the request up to 16 times with an exponential backoff.

4. (Optional) 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