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. Handling Webhooks events
Upon receiving a webhook event, you must acknowledge receipt of the successful notification by responding with a 2xx
status. In absence of this acknowledgement, our system will assume delivery failure and continue to retry up to 16 times over the course of 3 days using an exponential backoff scheme.
Duplicate events may occur as a result of concurrent processings within our system. Please ensure your webhook event handlers are idempotent.
Additionally, asynchronous processes and network delays may result in events getting sent or received out of order. We recommend using the event payload's timestamp
field, which indicates when the event occurred, to reorder the events in your system.
4. (Optional) Verifying event integrity
Gusto computes a hash message authenticate code (HMAC) of the event payload using the verification_token
provided in the verification step 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.
verification_token = '6590f590-3dba-495e-9bea-c361e1e2efc0'
hmac = OpenSSL::HMAC.hexdigest("SHA256", verification_token, request.body)
if hmac == request.headers['X-Gusto-Signature']
puts "the event was sent by Gusto"
else
puts 'do not trust the source'
end
Updated 3 months ago