Introduction

📘

NOTE

To get access and subscribe to our webhooks, email [email protected]

Webhooks allow apps to stay in sync with 7shifts data or perform an action after a specific event or change occurs. Webhooks are the preferred method to stay in sync or response to changes vs continuously polling for changes to a company's data models. For example, a webhook can notify your app of a creation of a new employee or a new schedule being published. Your app can then perform an action when the shift change occurs.

You will require an HTTP endpoint that can accept unauthenticated webhook requests with a POST method. Your endpoint must return a successful status code (2XX) prior to any complex logic that could cause a timeout.

The current webook events supported are:

All webhooks will include header information to help you determine which event and event they are for. The structure of the webhook headers are:

Header nameDescription
x-webhook-idInternal usage.
x-webhook-topicThe webhook topic this webhook corresponds to
x-company-idThe company_id for the webhook event
x-hmac-timestampUsed for calculating the hmac signature
x-hmac-signatureHash Message Authentication Code used to verify the source of the webhook.

To create the signature we use a SHA-256 algorithm to encode the webhook payload. The private key is the concatenation of the hmac timestamp and the OAuth grant GUID for the company in this format:

{timestamp}#{guid}

The timestamp is included in the header x-hmac-timestamp

The GUID is the company grant info that corresponds to the company_id this webhook is for. The company_id is provided in the header x-company-id.