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

# Webhooks

> How to use the Alex Webhooks API

## Introduction

Webhooks are a way for web applications to communicate with each other in real-time. They are user-defined HTTP callbacks that are triggered by specific events. When an event occurs, the source site makes an HTTP `POST` request to the URL configured for the webhook.

To set up the webhook, you need to log into your Alex dashboard, go to the Settings page, and add the URL where you want to receive the webhook notifications under `Integrations/Alex API`.

## Authentication

Every webhook request from Alex includes an `X-API-KEY` header containing your API key. Use this to verify that incoming requests are legitimately from Alex.

```http theme={null}
X-API-KEY: <your-api-key>
```

<Warning>
  Always validate the `X-API-KEY` header on your webhook endpoint to prevent
  unauthorized requests. Reject any request where the key does not match your
  API key.
</Warning>

## Webhook Events

Each webhook event has a specific payload that is sent to the URL configured for the webhook. The payload contains information about the event that triggered the webhook.

<Note>
  We now reference each completed interview using the `reportId`. This is
  equivalent to the `interviewId` in the Get Interviews route.
</Note>

The following are the events that trigger webhooks:

| Event Type            | Description                                                                                                                                   |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `session.started`     | Triggered once a candidate enters the room with Alex and starts (or resumes) that interview.                                                  |
| `session.paused`      | Sent when a candidate leaves an interview midway or it gets interrupted.                                                                      |
| `session.ended`       | Triggered once the candidate finishes their conversation with Alex and the end of the interview is reached (meaning they can't return to it). |
| `session.rescheduled` | Sent when a candidate reschedules their interview during the session. The interview is reset to a scheduled state with a new date/time.       |
| `session.completed`   | Sent once the evaluation is complete and the report is available. The resulting data is included in this event payload.                       |
| `session.shortlisted` | Sent once an interview is shortlisted in the Alex dashboard.                                                                                  |
| `session.rejected`    | Sent once an interview is rejected in the Alex dashboard.                                                                                     |

### `session.started`

This event is sent when a candidate enters the room with Alex and starts. It also gets sent if the candidate is resuming a paused interview.

**Example Payload:**

```json theme={null}
{
  event: "session.started"
  data: {
    candidateId: "candidateId",
    candidateEmail: "candidate@email.com",
    reportId: "reportId",
    positionId: "positionId",
    time: 1234567890,
  }
}
```

### `session.paused`

This event is sent when a candidate leaves an interview midway or it gets interrupted. The candidate left before the interview completed, so still has a chance to complete it.

**Example Payload:**

```json theme={null}
{
  event: "session.paused"
  data: {
    candidateId: "candidateId",
    candidateEmail: "candidate@email.com",
    reportId: "reportId",
    positionId: "positionId",
    time: 1234567890,
  }
}
```

### `session.ended`

This event is sent once the candidate finishes their conversation with Alex and the end of the interview is reached. At this point they can't return to the interview and their report is being generated.

**Example Payload:**

```json theme={null}
{
  event: "session.ended"
  data: {
    candidateId: "candidateId",
    candidateEmail: "candidate@email.com",
    reportId: "reportId",
    positionId: "positionId",
    time: 1234567890,
  }
}
```

### `session.rescheduled`

This event is sent when a candidate reschedules their interview during the session. The interview is moved back to a scheduled state with the new date and time.

**Example Payload:**

```json theme={null}
{
  event: "session.rescheduled"
  data: {
    candidateId: "candidateId",
    candidateEmail: "candidate@email.com",
    reportId: "reportId",
    positionId: "positionId",
    time: 1234567890,
  }
}
```

### `session.completed`

This event is triggered when an interview is completed.

**Example Payload:**

```json theme={null}
{
  event: "session.completed",
  data: {
    reportId: "reportId",
    candidateId: "candidateId",
    candidateEmail: "candidate@email.com",
    positionId: "positionId",
    overallScore: 70,
    overallFeedback: "The candidate did well in the interview overall ...",
    questionSummary: [
      {
        question: "What's the first code you ever wrote?",
        summary: "The candidate's first code was hello world in Python ..."
      },
      {
        question: "What's the most challenging project you've worked on?",
        summary: "The candidate worked on a project that involved ..."
      },
      ...
    ],
    skills: [
      {
        name: "Python",
        score: 80,
        feedback: "The candidate did well in the Python section ..."
      },
      {
        name: "JavaScript",
        score: 45,
        feedback: "The candidate struggled in the JavaScript section ..."
      },
      ...
    ],
    tags: [
      {
        name: "Work Authorization",
        value: "Yes",
        evidence: "The candidate confirmed they are authorized to work in the United States"
      },
      {
        name: "Education Level",
        value: "Bachelor's Degree",
        evidence: "The candidate provided a copy of their degree"
      },
      ...
    ],
    time: 1234567890,
    videoURL: "https://videoURL",
    pdfURL: "https://pdfURL"
  }
}
```

### `session.shortlisted`

This event is sent once an interview is shortlisted by a user in the Alex dashboard.

**Example Payload:**

```json theme={null}
{
  event: "session.shortlisted"
  data: {
    candidateId: "candidateId",
    candidateEmail: "candidate@email.com",
    reportId: "reportId",
    positionId: "positionId",
    time: 1234567890,
  }
}
```

### `session.rejected`

This event is sent once an interview is rejected by a user in the Alex dashboard.

**Example Payload:**

```json theme={null}
{
  event: "session.rejected"
  data: {
    candidateId: "candidateId",
    candidateEmail: "candidate@email.com",
    reportId: "reportId",
    positionId: "positionId",
    time: 1234567890,
  }
}
```