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 respond to changes, as compared with continuously polling for changes to a company's data. 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 employee or schedule change occurs.
To configure webhooks:
- Partners using OAuth clients please email [email protected].
- Companies can manage webhooks via the developer tools section under Company settings. Reference our Configure Company webhooks guide for more details.
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 webhook events supported are:
| Event | Topics |
|---|---|
| payroll_period | payroll_period.closed |
| schedule | schedule.published |
| time_punch | time_punch.created time_punch.edited time_punch.deleted |
| user | user.created user.modified user.deactivated user.reactivated |
| department | department.created department.modified department.deleted |
| location | location.created location.modified location.deleted |
| role | role.created role.modified role.deleted |
| authorization | authorization.revoked |
Webhooks configured by 7shifts may include header information to help you determine which event and event they are for. The structure of the webhook headers are:
| Header name | Description |
|---|---|
| x-webhook-id | Internal usage. |
| x-webhook-topic | The webhook topic this webhook corresponds to |
| x-company-id | The company_id for the webhook event |
| x-hmac-timestamp | Used for calculating the hmac signature |
| x-hmac-signature | Hash 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-timestampThe 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. |
Please note: hmac timestamps and hmac signatures will only be present in webhook event notifications configured by 7shifts. Webhooks configured by users directly in the 7shifts webapp will not contain hmac values in headers.