Webhooks

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.

X-API-KEY: <your-api-key>

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.

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.

We now reference each completed interview using the reportId. This is equivalent to the interviewId in the Get Interviews route.

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:

{
  event: "session.started"
  data: {
    candidateId: "candidateId",
    candidateEmail: "[email protected]",
    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:

{
  event: "session.paused"
  data: {
    candidateId: "candidateId",
    candidateEmail: "[email protected]",
    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:

{
  event: "session.ended"
  data: {
    candidateId: "candidateId",
    candidateEmail: "[email protected]",
    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:

{
  event: "session.rescheduled"
  data: {
    candidateId: "candidateId",
    candidateEmail: "[email protected]",
    reportId: "reportId",
    positionId: "positionId",
    time: 1234567890,
  }
}

`session.completed`

This event is triggered when an interview is completed. Example Payload:

{
  event: "session.completed",
  data: {
    reportId: "reportId",
    candidateId: "candidateId",
    candidateEmail: "[email protected]",
    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:

{
  event: "session.shortlisted"
  data: {
    candidateId: "candidateId",
    candidateEmail: "[email protected]",
    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:

{
  event: "session.rejected"
  data: {
    candidateId: "candidateId",
    candidateEmail: "[email protected]",
    reportId: "reportId",
    positionId: "positionId",
    time: 1234567890,
  }
}

API Documentation

Candidates

Reports

Positions

Templates

Partner Applications

Assessments

Introduction

Authentication

Webhook Events

`session.started`

`session.paused`

`session.ended`

`session.rescheduled`

`session.completed`

`session.shortlisted`

`session.rejected`

​Introduction

​Authentication

​Webhook Events

​session.started

​session.paused

​session.ended

​session.rescheduled

​session.completed

​session.shortlisted

​session.rejected

Introduction

Authentication

Webhook Events

`session.started`

`session.paused`

`session.ended`

`session.rescheduled`

`session.completed`

`session.shortlisted`

`session.rejected`