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
subscription_types. The URL will receive POST requests from Gusto. The provided
subscription_types map to Gusto Embedded entities.
Employeeis included as a
subscription_type, when partner managed company employees are created or modified, the callback
URLwill receive POST notification events comprised of the associated employee represented as JSON.
Before the subscription URL will gets sent entity event updates, it will first receive a
verification_token of the form
The subscriber received verification_token must be verified.
This ensures that the creator of the webhook subscription controls the registered subscription URL.
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
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