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 asubscription_type
, when partner managed company employees are created or modified, the callbackURL
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
Updated 9 months ago