Login

StackOne Webhooks

Describes how to use the StackOne webhooks functionality

Overview

StackOne allows configuring multiple Webhooks to establish alerts' communication between your application and StackOne servers. After creating a webhook, you will need to test Webhooks by specifying:
example payload
your customized webhook integration code

Create a webhook

  1. After selecting a StackOne project, you will see the Webhooks section in the left-hand-side menu.

  2. You can now create and configure a new webhook by clicking the Add Webhook button

  3. Input in the Webhook URL field a valid URL that StackOne should send a request to whenever one of the previously selected event occurs.

  4. Select the events that your webhook should be triggered on.

    1. StackOne leverages synthetic webhooks by polling the underlying provider records every hour and comparing stored hashes. The poll time can be adapted based on your needs and no PII is stored as part of this process.
  5. Finally, click on the Save Webhook button. You should now see the Webhook on the webhooks page.

  6. Take note of the webhook secret displayed in the webhook listing page as it will allow you to authenticate more securely webhooks coming from StackOne

    1. As a relatively less secure but simpler alternative, you can also authenticate events sent by StackOne by adding a custom query parameter to your webhook URL eg ?token=unique_secret_token and verify this parameter's presence when receiving the request.

event list and associated record_type

record_typeCategoryEventsSynthetic Webhook
accountStackOneaccount.created account.updated account.deletedReal-time
employeesHRIShris_employees.created hris_employees.updated hris_employees.deleted
employmentsHRIShris_employments.created hris_employments.updated hris_employments.deleted
interviewsATSats_interviews.created ats_interviews.updated ats_interviews.deleted
applicationsATSats_applications.created ats_applications.updated ats_applications.deleted
candidatesATSats_candidates.created ats_candidates.updated ats_candidates.deleted
job_postingsATSats_job_postings.created ats_job_postings.updated ats_job_postings.deleted
jobsATSats_jobs.created ats_jobs.updated ats_jobs.deleted
listsATSats_lists.created ats_lists.updated ats_lists.deleted
usersATSats_users.created ats_users.updated ats_users.deleted
contactsCRMcrm_contacts.created crm_contacts.updated crm_contacts.deleted
accountsCRMcrm_accounts.created crm_accounts.updated crm_accounts.deleted

📝

Note:

The webhook settings such as URL and Events can be updated at any point after creating the webhook by returning to the Webhooks page and clicking on the webhook you would like to update.
You can also delete the webhook if it's no longer needed (irreversible action).

Testing Webhooks

Example Payload

Accounts-based webhooks payload will follow the following interface:

{
  project_id: string, // the ID of the StackOne project
  event: 'account.updated' | 'account.created' | 'account.deleted' | 'hris_employees.updated', 'hris_employees.created',
  event_date: 'string', // date as ISO string (eg: '2023-07-03T01:55:47.217Z')
  record_type: 'account',
  record_id: string | number, // In the case of accounts-based events - this will be the account ID
  sent_at: 'string', // date as ISO string (eg: '2023-07-03T01:55:47.217Z')
  account_id: string, // This will always be the Account ID
  origin_owner_id?: string, // unique indentifier used to track customers or organizations
  origin_owner_name?: string, // human-readable name associated with Origin Owner ID
  origin_username?: string, // username responsible for connecting the tool
  setup_information?: object, // extra information used to setup the account
}

Account updated example

{
  "project_id": "acmeinc-27270",
  "account_id": "41220118784113397989",
  "event": "account.updated",
  "event_date": "2023-11-01T13:10:31.408Z",
  "record_type": "account",
  "record_id": "41220118784113397989",
  "sent_at": "2023-11-01T13:10:31.418Z",
  "origin_owner_id": "unique-org-identifier",
  "origin_owner_name": "Test organization",
  "origin_username": "sample-user",
  "setup_information": {
    "domain": "companytest"
  }
}

Employee updated example

{
  "project_id": "acmeinc-27270",
  "account_id": "41260118784113327989",
  "event": "hris_employees.updated",
  "event_date": "2023-11-01T15:09:22.961Z",
  "record_type": "employees",
  "record_id": "3223323715753018140",
  "sent_at": "2023-11-01T15:09:22.978Z"
}

A x-stackone-signature header will be added to all webhook requests, e.g.,'x-stackone-signature': 'jqzLV78Lkg5RhZgx6nRA1FLIYBkqoclBdRrNizjlZcU'. This header will contain a hmac sha256 hash of the given payload using the Signature Secret previously given as a secret key during hashing.

⚠️

3rd party Webhook generators:

You can easily test the account-based webhooks by using a third-party webhook creation tool such as https://webhook.site or https://typedwebhook.tools/ or by setting-up a proxy to your localhost via ngrok.

StackOne is not affiliated with these websites.

Sample Webhook consumer code

// index.js
import express from 'express';
import bodyParser from 'body-parser';
import { createHmac } from 'crypto';
const app = express();

// Replace with the signing secret string displayed on the Stackone webhooks details page
const STACKONE_WEBHOOK_SIGNATURE =
  'S-gQTtwraolKVsY88OvQNZ-TlGrHw9mvHKp-ls8Co9CkOADQc1VSeCZ_2hDK6oWuKUd_4qxjRLzoEGYA9JVCNg';


/**
 * The function checks if a given signature is valid by comparing it with the payload hash using a signing secret.
 * @param signature - The `signature` parameter is the signature value that you want to validate. It is typically a string
 * representing the cryptographic signature of the `payload` parameter.
 * @param payload - The payload is the data that needs to be signed. It can be any string or object that you want to verify
 * the integrity of.
 * @param signingSecret - The `signingSecret` parameter is a secret key used for generating the signature. It is a string
 * value that should be kept confidential and known only to the parties involved in the signature verification process.
 * @returns a boolean value indicating whether the calculated hash is equal to the provided signature.
 */
function isSignatureValid(signature, payload, signingSecret) {
  const hash = createHmac('sha256', signingSecret)
    .update(payload)
    .digest('base64url');
  return hash === signature;
}

const jsonParser = bodyParser.json();

app.post('/integrations/webhook/accounts', jsonParser, (req, res) => {
  const signature = req.headers['x-stackone-signature'];
  if (
    !signature ||
    !isSignatureValid(
      req.headers['x-stackone-signature'],
      JSON.stringify(req.body),
      STACKONE_WEBHOOK_SIGNATURE,
    )
  ) {
    return res.status(401).send('Unauthorized');
  }
  // Do something with the payload
  console.log(req.body);

  // The webhook URL should return a 200 upon successful processing of the event. The response does not need to include anything else.
  return res.status(200).send(`Thank you for the account webhook event ❤️`);
});

console.log('listening on port 3333');
app.listen(3333);

// This sample server can be run via `node index.js`