Sapling - Subscribing to Sapling Webhooks – Kallidus

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

Please note that you'll need to use an integration platform (like Workato or Zapier) to receive Sapling webhooks and process them into actions in your downstream apps (like Slack).

This article covers the following topics:

Webhooks available in Sapling
Create and subscribe to a webhook
Example webhook payloads
Pro tips💡

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

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.

Learn more about validating requests from Sapling with the token here.

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