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.
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 webook 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 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. |