Introduction
Create webhook subscriptions to update external systems when key events in Sapling occur.
What are webhooks?
Instead of one system repeatedly calling another system's API to ask if some event has occurred (a process called polling), the system can subscribe to receive updates when that specific something occurs through a webhook. Once notified, the system can then call back for more details if needed.
Webhooks allow you to send real-time data to the rest of your tech stack
Triggered specifically by milestone events in Sapling (think things like role changes, profile updates, or key dates reached), webhooks then inform the rest of your tools about these events – triggering actions that help automate key processes.
While webhooks can be used in an infinite number of ways – a few examples of how People Teams leverage Sapling Webhooks include:
-
Posting a message on Slack when a full-time team member has a job change
-
Adding hires to a payroll system used only by team members in a specific country
-
Triggering calendar events to be created for birthdays
-
Update your internal business analytics platform once an employee has reached their 1-year anniversary
Webhooks available in Sapling
Sapling currently supports six different event types to which you can subscribe:
- New Pending Hire
- Stage Started
- Stage Completed
- Profile Changed
- Job Details Changed
- Key Date Reached
- Onboarding
- Offboarding
Examples of the payload you can expect for each of those event types are below.
Stage Events
Stage completed and the stage started is the type of webhooks that trigger when a user’s stage is changed in Sapling. Each stage transition webhook event is described below, in each process, two webhooks will be triggered. One for the stage was completed and one for the stage started.
Process | Stage Completed | Stage Started |
When the onboarding event gets completed, Two webhooks will be triggered in this process:
|
Incomplete | Invited |
When a user starts the preboarding flow and changes their password successfully. | Invited | Preboarding |
When the user completes the preboarding flow successfully. | Preboarding | Pre-Start |
When the start date of the user has been reached. | Pre-Start | First-Week |
When one week after the start date has passed. | First-Week | First-Month |
When one month after the start date has passed. | First-Month | Registered |
When the user is offboarded, the new stage will be based on the termination date.
|
Registered | Offboarding / Last Month / Last Week / Departed |
Lifecycle Events
The Onboarding and Offboarding type of webhooks trigger when a user’s onboarding or offboarding events are started, completed, or canceled in Sapling. Each event webhook event is described below, in each process, two webhooks will be triggered. One for onboarding and one for offboarding.
Process | Event Started | Event Completed | Event Cancelled |
Onboarding | When an admin completes the user's onboarding flow. | When a user's stage changes from preboarding to one of the following stages: Pre-Start, 1st Week, 1st Month, or Ramping Up. | When a user is deleted from the dashboard or directly from their profile and that user's stage is one of the following: Invited, Preboarding, or Pre-Start. |
Offboarding | When an admin completes the user's offboarding flow. | When a user's state changes from Active to Inactive. | When a user's offboarding is canceled on the offboarding dashboard. |
Create and subscribe to a webhook
*You can easily create webhooks from Sapling directly as shown below, but your developers may be excited to know you can also manage your webhook subscriptions directly through the Sapling Public API as well.
*Note: (Ensure there is a webhook token present before attempting to connect any webhooks)
To create a new webhook, navigate to Administration Tools > Integrations > Webhooks, then click "Create new".
Select from the 6 key event type options to create a webhook subscription; note that some webhooks allow further filtering to monitor specific stages, dates, or fields.
Don't have an active delivery URL up and running yet? Use a testing site like https://webhook.site/ to stage your webhook subscription.
Optionally, narrow down the webhook by Location, Department, or Employment Status filters; then click "Test".
To ensure that your delivery URL only receives traffic from authorized Sapling calls, copy the webhook secret token for authentication. You can revoke that secret token at any time if needed; this will disable delivery of ALL webhooks messages based on that token.
Leverage the Actions menu to Deactivate, Test, Edit, or Delete existing webhooks.
Clicking on the view icon opens additional detail about the webhook including a full delivery log for quick troubleshooting or verification.
For steps on how to use Webhook Token to validate Requests from Sapling, visit here.
Example webhook payloads
The exact details of the payload received depend on the event type and your specific account configuration (e.g. what Job Details fields are you tracking in Sapling). The following examples are for illustrative purposes.
New Pending Hire
Fires when a pending hire is added or removed from Sapling.
{
"webhook_event": {
"customer": {
"domain": "rocketship.saplingapp.io",
"companyID": "znnIro0d7vU"
}
},
"pending_hire": {
"action": "created",
"source": "https://www.saplinghr.com",
"personalEmail": "webhookexample@trysapling.com",
"firstName": "Pelina",
"preferredName": null,
"lastName": "Hook",
"startDate": "24/05/2021",
"jobTitle": "QA Lead",
"department": "Engineering",
"location": "Atlanta",
"status": "active",
"employmentStatus": "Full-Time",
"pendingHireId": "1621580194817aa702-af74-48a4-8bfc"
}
}
Stage Started
Fires when a user starts a new stage.
{
"webhook_event": {
"customer": {
"domain": "rocketship.saplingapp.io",
"companyID": "znnIro0d7vU"
}
},
"user": {
"email": "sarah@gmail.com",
"firstName": "Sarah Salem",
"preferredName": "Reichert",
"lastName": "Salem",
"startDate": "2021-05-14",
"jobTitle": "Software Engineer",
"department": "Development",
"location": "San Francisco",
"status": "active",
"employmentStatus": "part time",
"userId": "7dfd4316f-1d4d-4da7-8d6e",
"StageStarted": "preboarding"
}
}
Stage Completed
Fires when a user completes a stage.
{
"webhook_event": {
"customer": {
"domain": "rocketship.saplingapp.io",
"companyID": "znnIro0d7vU"
}
},
"user": {
"email": "sarah@gmail.com",
"firstName": "Sarah Salem",
"preferredName": "Reichert",
"lastName": "Salem",
"startDate": "2021-05-14",
"jobTitle": "Software Engineer",
"department": "Development",
"location": "San Francisco",
"status": "active",
"employmentStatus": "part time",
"userId": "7dfd4316f-1d4d-4da7-8d6e",
"StageCompleted": "preboarding"
}
}
Profile Changed
Fires when a specific field (or group of fields) on a user’s profile is changed.
{
"webhook_event": {
"customer": {
"domain": "rocketship.saplingapp.io",
"companyID": "znnIro0d7vU"
}
},
"user": {
"email": "sarah@gmail.com",
"userId": "7dfd4316f-1d4d-4da7-8d6e",
"fields_changed": {
"date": "21/05/2021",
"fields": [
{
"fieldName": "About",
"oldValue": null,
"newValue": "Adding some new details about me!"
}
]
}
}
}
Job Details Changed
Fires when a specific field (or group of fields) on a user’s custom tables is changed (role, compensation, status, or general custom tables).
{
"webhook_event": {
"customer": {
"domain": "rocketship.saplingapp.io",
"companyID": "znnIro0d7vU"
}
},
"user": {
"email": "sarah@gmail.com",
"userId": "7dfd4316f-1d4d-4da7-8d6e",
"fields_changed": {
"date": "21/05/2021",
"fields": [
{
"tableName": "Role Information",
"fieldName": "Department",
"oldValue": "Sales",
"newValue": "Administration",
"effectiveDate": "24/05/2021"
},
{
"tableName": "Role Information",
"fieldName": "Location",
"oldValue": Australia,
"newValue": "Sydney",
"effectiveDate": "24/05/2021"
}
]
}
}
}
Key Date Reached
Fires when a specific key date field (or group of key date fields) on a user’s profile is reached (i.e. = today).
{
"webhook_event": {
"customer": {
"domain": "rocketship.saplingapp.io",
"companyID": "znnIro0d7vU"
}
},
"user": {
"email": "sarah@gmail.com",
"firstName": "Sarah Salem",
"preferredName": "Reichert",
"lastName": "Salem",
"startDate": "2021-05-14",
"jobTitle": "Software Engineer",
"department": "Development",
"location": "San Francisco",
"status": "active",
"employmentStatus": "part time",
"userId": "7dfd4316f-1d4d-4da7-8d6e",
"keydatesReached": {
"date": "2021-05-21",
"dateType": "birthday"
}
}
}
Onboarding Event
Fires when an event on a user’s profile is reached (i.e. = Started).
{ "webhook_event": { "customer": { "domain": "rocketship.saplingapp.io", "companyID": "znnIr0d7vU" }, "eventType": "onboarding", "eventTime": "2022-04-14T22:03:58.665+00:00", "eventActivity": { "activityState": "started", "activityInitiatedByGuid": 23212 }, "email": "sarah@rocketship.com", "personalEmail": "sarah@gmail.com", "firstName": "Sarah", "preferredName": "Sarah", "lastName": "Salem", "userGuid": "106003caefb6ab-bc08-4fb2-b9e2-428f7cfe9657", "userId": 106003, "status": "active", "current_stage": "invited", "startDate": "2022-04-29", "accountProvision": {
"accountProvider": null, "accountProvisionRequest": "No",
"accountProvisionSchedule": null, "accountProvisionTime": null } } }
Offboarding Event
Fires when an event on a user’s profile is reached (i.e. = Started).
{ "webhook_event": { "customer": { "domain": "rocketship.saplingapp.io", "companyID": "znnIr0d7vU" }, "eventType": "offboarding", "eventTime": "2022-04-14T22:03:58.665+00:00", "eventActivity": { "activityState": "started", "activityInitiatedByGuid": 23212 }, "email": "sarah@rocketship.com", "personalEmail": "sarah@gmail.com", "firstName": "Sarah", "preferredName": "Sarah", "lastName": "Salem", "userGuid": "106003caefb6ab-bc08-4fb2-b9e2-428f7cfe9657", "userId": 106003, "status": "active", "current_stage": "last_week", "terminationDate": "2022-04-22",
"lastDayWorked": "2022-04-20",
"terminationType": null,
"eligibleForRehire": null, "accessCutOff": {
"accessCutOffSchedule": "default", "accountCutOffTime": null } } }
Pro tips💡
- Webhooks are triggered for new hires and rehires when they have reached the Invited stage.
- If an app supports inbound updates from webhooks, then they likely have documentation (or at least a feature) that highlights what URL to use for something like Sapling.
- A delivery URL for a webhook is nothing more than a URL from the receiving application that Sapling would have access to call. This URL acts as a special voicemail-only phone number - the receiving app regularly checks the voicemails we've left and then takes action based on those voicemails.
Comments
0 comments
Please sign in to leave a comment.