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
Updated 3 months ago