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

# Webhook Events — Cutshort Event Types and Payloads

> Reference for all Cutshort webhook event types. Covers payload shapes for candidate, invite, offer, and job events that fire in your hiring pipeline.

Cutshort fires webhook events when key actions occur in your hiring pipeline. Each event delivers a POST request to your registered endpoint with a JSON payload containing event details and the affected resource data.

## Event Payload Structure

Every webhook request shares the same top-level envelope:

```json theme={null}
{
  "id": "evt_3mKpL8nQ",
  "event": "candidate.shortlisted",
  "created_at": "2024-01-15T10:30:00Z",
  "organization_id": "org_7hWx4mPq",
  "data": { ... }
}
```

<ResponseField name="id" type="string">
  Unique event ID. Use this field to deduplicate events in case your endpoint receives the same delivery more than once.
</ResponseField>

<ResponseField name="event" type="string">
  The event type identifier. See the full list of event types below.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp for when the event occurred.
</ResponseField>

<ResponseField name="organization_id" type="string">
  Your Cutshort organization ID.
</ResponseField>

<ResponseField name="data" type="object">
  The event-specific payload. Shape varies by event type — see each event below.
</ResponseField>

## Event Reference

<AccordionGroup>
  <Accordion title="candidate.shortlisted — Candidate added to a job shortlist">
    Fired when Cutshort's AI matching engine adds a candidate to a job shortlist.

    **Payload fields**

    | Field                | Type             | Description                                        |
    | -------------------- | ---------------- | -------------------------------------------------- |
    | `candidate_id`       | string           | ID of the shortlisted candidate                    |
    | `job_id`             | string           | ID of the job the candidate was shortlisted for    |
    | `match_score`        | integer          | AI match score (0–100) for this candidate–job pair |
    | `match_reasons`      | array of strings | Human-readable reasons for the match               |
    | `candidate.name`     | string           | Candidate's full name                              |
    | `candidate.headline` | string           | Candidate's current role or headline               |
    | `candidate.location` | string           | Candidate's city or region                         |

    ```json theme={null}
    {
      "id": "evt_3mKpL8nQ",
      "event": "candidate.shortlisted",
      "created_at": "2024-01-15T10:30:00Z",
      "organization_id": "org_7hWx4mPq",
      "data": {
        "candidate_id": "cand_8f3kL9mN",
        "job_id": "job_4xRt2wPv",
        "match_score": 92,
        "match_reasons": [
          "5 years Python experience matches requirement",
          "B2C product background aligns with role context"
        ],
        "candidate": {
          "name": "Priya Menon",
          "headline": "Senior Python Engineer",
          "location": "Bengaluru"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="candidate.stage_changed — Candidate moved to a new pipeline stage">
    Fired when a candidate advances or moves to a different stage in the hiring pipeline.

    **Payload fields**

    | Field          | Type   | Description                            |
    | -------------- | ------ | -------------------------------------- |
    | `candidate_id` | string | ID of the candidate                    |
    | `job_id`       | string | ID of the associated job               |
    | `from_stage`   | string | Stage the candidate moved from         |
    | `to_stage`     | string | Stage the candidate moved to           |
    | `changed_at`   | string | ISO 8601 timestamp of the stage change |

    **Valid stage values:** `shortlisted`, `invited`, `interested`, `screening`, `interview`, `offer`, `hired`, `rejected`

    ```json theme={null}
    {
      "id": "evt_9nBqW2xZ",
      "event": "candidate.stage_changed",
      "created_at": "2024-01-16T09:15:00Z",
      "organization_id": "org_7hWx4mPq",
      "data": {
        "candidate_id": "cand_8f3kL9mN",
        "job_id": "job_4xRt2wPv",
        "from_stage": "invited",
        "to_stage": "interested",
        "changed_at": "2024-01-16T09:15:00Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="invite.accepted — Candidate expressed interest in an outreach invite">
    Fired when a candidate clicks "interested" on an outreach invite sent via WhatsApp or email.

    **Payload fields**

    | Field          | Type   | Description                                                           |
    | -------------- | ------ | --------------------------------------------------------------------- |
    | `candidate_id` | string | ID of the candidate who accepted                                      |
    | `job_id`       | string | ID of the job the invite was for                                      |
    | `channel`      | string | Channel through which the candidate responded (`whatsapp` or `email`) |
    | `accepted_at`  | string | ISO 8601 timestamp of the acceptance                                  |

    ```json theme={null}
    {
      "id": "evt_5rDtY7kV",
      "event": "invite.accepted",
      "created_at": "2024-01-17T14:22:00Z",
      "organization_id": "org_7hWx4mPq",
      "data": {
        "candidate_id": "cand_8f3kL9mN",
        "job_id": "job_4xRt2wPv",
        "channel": "whatsapp",
        "accepted_at": "2024-01-17T14:22:00Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="invite.declined — Candidate declined an outreach invite">
    Fired when a candidate explicitly declines an invite or marks themselves as not interested.

    **Payload fields**

    | Field          | Type   | Description                                                          |
    | -------------- | ------ | -------------------------------------------------------------------- |
    | `candidate_id` | string | ID of the candidate who declined                                     |
    | `job_id`       | string | ID of the job the invite was for                                     |
    | `channel`      | string | Channel through which the candidate declined (`whatsapp` or `email`) |
    | `declined_at`  | string | ISO 8601 timestamp of the decline                                    |

    ```json theme={null}
    {
      "id": "evt_2sHwM6pJ",
      "event": "invite.declined",
      "created_at": "2024-01-17T16:05:00Z",
      "organization_id": "org_7hWx4mPq",
      "data": {
        "candidate_id": "cand_2pQr7sYk",
        "job_id": "job_4xRt2wPv",
        "channel": "email",
        "declined_at": "2024-01-17T16:05:00Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="offer.made — Offer letter sent to a candidate">
    Fired when your team sends an offer letter to a candidate through Cutshort.

    **Payload fields**

    | Field                            | Type   | Description                               |
    | -------------------------------- | ------ | ----------------------------------------- |
    | `candidate_id`                   | string | ID of the candidate receiving the offer   |
    | `job_id`                         | string | ID of the job the offer is for            |
    | `offer_details.ctc`              | string | Offered cost-to-company (e.g. `"18 LPA"`) |
    | `offer_details.joining_date`     | string | ISO 8601 expected joining date            |
    | `offer_details.offer_letter_url` | string | Signed URL to download the offer letter   |

    ```json theme={null}
    {
      "id": "evt_7cFnP4qX",
      "event": "offer.made",
      "created_at": "2024-01-20T11:00:00Z",
      "organization_id": "org_7hWx4mPq",
      "data": {
        "candidate_id": "cand_8f3kL9mN",
        "job_id": "job_4xRt2wPv",
        "offer_details": {
          "ctc": "18 LPA",
          "joining_date": "2024-02-12T00:00:00Z",
          "offer_letter_url": "https://files.cutshort.io/offers/cand_8f3kL9mN_offer.pdf"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="job.closed — A job was closed">
    Fired when a job is closed — either after a successful hire, a manual cancellation, or expiry.

    **Payload fields**

    | Field       | Type   | Description                                                 |
    | ----------- | ------ | ----------------------------------------------------------- |
    | `job_id`    | string | ID of the closed job                                        |
    | `title`     | string | Title of the closed job                                     |
    | `closed_at` | string | ISO 8601 timestamp of when the job was closed               |
    | `reason`    | string | Why the job was closed: `filled`, `cancelled`, or `expired` |

    ```json theme={null}
    {
      "id": "evt_1aGwR9tL",
      "event": "job.closed",
      "created_at": "2024-01-22T18:00:00Z",
      "organization_id": "org_7hWx4mPq",
      "data": {
        "job_id": "job_4xRt2wPv",
        "title": "Senior Backend Engineer",
        "closed_at": "2024-01-22T18:00:00Z",
        "reason": "filled"
      }
    }
    ```
  </Accordion>
</AccordionGroup>