> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CATS Webhook Setup Guide

> Configure CATS to deliver events to StackOne.

## Prerequisites

Before continuing, you should have already completed the following for this connector:

<Steps>
  <Step title="Configure the Connector">
    Enable the connector and set up its connector profile in your project. See <a href="/connect/managing-connectors/overview">Managing Connectors</a>.

    <Columns cols={2}>
      <Card title="Connector Profile" href="/connectors/cats/guides/connector-profile/api-key" icon="https://stackone-logos.com/api/cats/filled/svg" horizontal>
        CATS - API Key
      </Card>
    </Columns>
  </Step>

  <Step title="Link an Account">
    Connect an account using <a href="/embed/account-linking/overview">StackOne Hub</a> or <a href="/embed/account-linking/auth-link">Auth Link</a>.

    <Columns cols={2}>
      <Card title="Link Account" href="/connectors/cats/guides/link-account/api-key" icon="https://stackone-logos.com/api/cats/filled/svg" horizontal>
        CATS - API Key
      </Card>
    </Columns>
  </Step>
</Steps>

<section data-guide-section data-guide-scopes="">
  <h2>How webhooks are set up</h2>

  <p>StackOne creates and manages the CATS webhook subscriptions automatically when the account is connected, and removes them when it is disconnected — there is nothing to paste into CATS and no URL to copy.</p>

  <Steps>
    <Step title="Enable the WebHooks integration in CATS">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Webhooks are an add-on in CATS. In CATS, click your avatar in the top right, go to <strong>Administration</strong>, open <strong>Integrations</strong> and make sure <strong>WebHooks</strong> 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.</p>
      </div>
    </Step>

    <Step title="Enable the events you need">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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 <strong>Administration</strong> → <strong>Events & Webhooks</strong>; leave it as it is, because StackOne creates, updates and removes it for you.</p>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>The events below can be enabled for this connection. Only the events you select in StackOne are subscribed in CATS and delivered.</p>

  <Steps>
    <Step title="Review candidate events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to candidate records.</p>

        <ul>
          <li><strong>Candidate Created</strong> (`candidate.created`) — Fired when a candidate is created.</li>
          <li><strong>Candidate Updated</strong> (`candidate.updated`) — Fired when a candidate record is modified.</li>
          <li><strong>Candidate Deleted</strong> (`candidate.deleted`) — Fired when a candidate is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review job order events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to job orders.</p>

        <ul>
          <li><strong>Job Created</strong> (`job.created`) — Fired when a job order is created.</li>
          <li><strong>Job Updated</strong> (`job.updated`) — Fired when a job order is modified.</li>
          <li><strong>Job Deleted</strong> (`job.deleted`) — Fired when a job order is deleted.</li>
          <li><strong>Job Status Changed</strong> (`job.status_changed`) — Fired when a job order's status changes. The payload carries both the previous and the new status id.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review pipeline events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to pipelines — a candidate attached to a job order.</p>

        <ul>
          <li><strong>Pipeline Created</strong> (`pipeline.created`) — Fired when a candidate is added to a job order's pipeline.</li>
          <li><strong>Pipeline Deleted</strong> (`pipeline.deleted`) — Fired when a candidate is removed from a job order's pipeline.</li>
          <li><strong>Pipeline Status Changed</strong> (`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.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review contact events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to contacts at client companies.</p>

        <ul>
          <li><strong>Contact Created</strong> (`contact.created`) — Fired when a contact is created.</li>
          <li><strong>Contact Updated</strong> (`contact.updated`) — Fired when a contact record is modified.</li>
          <li><strong>Contact Deleted</strong> (`contact.deleted`) — Fired when a contact is deleted.</li>
          <li><strong>Contact Status Changed</strong> (`contact.status_changed`) — Fired when a contact's status changes. The payload carries both the previous and the new status id.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review company events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to client companies.</p>

        <ul>
          <li><strong>Company Created</strong> (`company.created`) — Fired when a company is created.</li>
          <li><strong>Company Updated</strong> (`company.updated`) — Fired when a company record is modified.</li>
          <li><strong>Company Deleted</strong> (`company.deleted`) — Fired when a company is deleted.</li>
          <li><strong>Company Status Changed</strong> (`company.status_changed`) — Fired when a company's status changes. The payload carries both the previous and the new status id.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review activity events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to logged activities such as calls, emails and meetings.</p>

        <ul>
          <li><strong>Activity Created</strong> (`activity.created`) — Fired when an activity is logged against a record.</li>
          <li><strong>Activity Updated</strong> (`activity.updated`) — Fired when a logged activity is modified.</li>
          <li><strong>Activity Deleted</strong> (`activity.deleted`) — Fired when a logged activity is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review user events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to the user accounts on your CATS account.</p>

        <ul>
          <li><strong>User Created</strong> (`user.created`) — Fired when a user is added to the account.</li>
          <li><strong>User Updated</strong> (`user.updated`) — Fired when a user's details or access level change.</li>
          <li><strong>User Deleted</strong> (`user.deleted`) — Fired when a user is removed from the account.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>How CATS delivers events to StackOne.</p>

  <Steps>
    <Step title="Inspect event payloads">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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`.</p>
      </div>
    </Step>

    <Step title="Read the embedded record">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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.</p>
      </div>
    </Step>

    <Step title="Handle delete events without an embedded record">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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.</p>
      </div>
    </Step>

    <Step title="Plan for one delivery per record on bulk changes">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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.</p>
      </div>
    </Step>

    <Step title="Verify deliveries">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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.</p>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.