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

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"
}
}
}

Did this answer your question?