CATS Webhook Setup Guide

Webhooks are an add-on in CATS. In CATS, click your avatar in the top right, go to Administration, open Integrations and make sure WebHooks is enabled. If the option is unavailable on your plan, contact CATS to upgrade — without it CATS rejects webhook subscriptions and no events are delivered.

When the connection is established, StackOne generates a unique callback URL for it and creates a single CATS webhook subscription covering every event you enable in StackOne. Only the events you enable are subscribed — CATS does not deliver events you have not subscribed to. The subscription is visible under Administration → Events & Webhooks; leave it as it is, because StackOne creates, updates and removes it for you.

Events related to candidate records.

• Candidate Created (candidate.created) — Fired when a candidate is created.
• Candidate Updated (candidate.updated) — Fired when a candidate record is modified.
• Candidate Deleted (candidate.deleted) — Fired when a candidate is deleted.

Events related to job orders.

• Job Created (job.created) — Fired when a job order is created.
• Job Updated (job.updated) — Fired when a job order is modified.
• Job Deleted (job.deleted) — Fired when a job order is deleted.
• Job Status Changed (job.status_changed) — Fired when a job order’s status changes. The payload carries both the previous and the new status id.

Events related to pipelines — a candidate attached to a job order.

• Pipeline Created (pipeline.created) — Fired when a candidate is added to a job order’s pipeline.
• Pipeline Deleted (pipeline.deleted) — Fired when a candidate is removed from a job order’s pipeline.
• Pipeline Status Changed (pipeline.status_changed) — Fired when a candidate moves to a different pipeline status, such as from Submitted to Interviewing. The payload carries both the previous and the new status id.

Events related to contacts at client companies.

• Contact Created (contact.created) — Fired when a contact is created.
• Contact Updated (contact.updated) — Fired when a contact record is modified.
• Contact Deleted (contact.deleted) — Fired when a contact is deleted.
• Contact Status Changed (contact.status_changed) — Fired when a contact’s status changes. The payload carries both the previous and the new status id.

Events related to client companies.

• Company Created (company.created) — Fired when a company is created.
• Company Updated (company.updated) — Fired when a company record is modified.
• Company Deleted (company.deleted) — Fired when a company is deleted.
• Company Status Changed (company.status_changed) — Fired when a company’s status changes. The payload carries both the previous and the new status id.

Events related to logged activities such as calls, emails and meetings.

• Activity Created (activity.created) — Fired when an activity is logged against a record.
• Activity Updated (activity.updated) — Fired when a logged activity is modified.
• Activity Deleted (activity.deleted) — Fired when a logged activity is deleted.

Events related to the user accounts on your CATS account.

• User Created (user.created) — Fired when a user is added to the account.
• User Updated (user.updated) — Fired when a user’s details or access level change.
• User Deleted (user.deleted) — Fired when a user is removed from the account.

CATS sends each event as an HTTP POST with a JSON body containing the event name in an event field (for example candidate.created) and the id of the affected record in a field named after its type (candidate_id, job_id, pipeline_id, and so on). Status change events additionally carry previous_status_id and new_status_id.

Create, update and status change deliveries embed the full affected record under _embedded, so the record does not have to be fetched separately. Webhooks embed up to 1000 of each related type — far more than the 25 returned by the REST endpoints — so all custom fields arrive with the event.

Delete events are the exception: they carry only the event name, the deleted record’s id, the id of the user who deleted it and the event date. There is no _embedded or _links block, because the record no longer exists. pipeline.deleted additionally reports the candidate_id and job_id the pipeline connected.

CATS delivers one event per record, including for mass updates made in the CATS UI. Editing a large number of records at once therefore produces a burst of individual events rather than a single batched one.

CATS signs every delivery. The X-Signature header holds an HMAC-SHA256 digest of the request body concatenated with the X-Request-Id header value, keyed with the signing secret StackOne registers when it creates the subscription. StackOne verifies this signature, and the unique per-connection callback URL identifies the account.