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

*Note: 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 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:

  • One for completing the incomplete stage.

  • A second one for starting the invited stage.

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.

  • If the termination date is next month then the new stage will be offboarding.

  • If the termination date is in the next month then the new stage will be last month.

  • If the termination date is in the next week or the current date then the new stage will be last week.

  • If the termination date is in the past, then the new stage will be departed.

Registered

Offboarding / Last Month / Last Week / Departed

Examples of the payload you can expect for each of those event types are below.


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.

To create a new webhook, navigate to Home > 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 specifics 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 3 dot menu to Deactivate, Test, Edit, or Delete existing webhooks.

Opening the side panel provides additional detail about the webhook including a full delivery log for quick troubleshooting or verification.


Example webhook payloads

The exact details of the payload received depends on the event type and your specific account configuration (e.g. what Job Details fields are your 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"
}
}
}


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.

Did this answer your question?