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.

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: "[e-mail]",
    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: "[e-mail]",
    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: "[e-mail]",
    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: "[e-mail]",
    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: "[e-mail]",
    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: "[e-mail]",
    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: "[e-mail]",
    reportId: "reportId",
    positionId: "positionId",
    time: 1234567890,
  }
}