Articles in this section

See more

Sapling - Subscribing to Sapling Webhooks

Avatar
Brian Craft
  • Updated
Follow

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

 

This article covers the following topics: 

 

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

 

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.
 

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.
*Note: (Ensure there is a webhook token present before attempting to connect any webhooks)

To create a new webhook, navigate to Home > Integrations > Webhooks, then click "Create new".

mceclip0.png

 

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

 

mceclip1.png

 

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.

Related articles

Comments

0 comments

Please sign in to leave a comment.