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

# Webhook events

> Every event InterviewFlowAI sends to your webhook endpoint, and the data in each one.

When something happens with a Candidate, InterviewFlowAI sends a `POST` request with a JSON body to each endpoint subscribed to that event. Turn webhooks on for an Interviewer in the dashboard (see [Webhooks](https://docs.interviewflowai.com/platform/webhooks.md)) or with `webhookConfig` when you [create an Interviewer](https://docs.interviewflowai.com/api-reference/interviewers/create.md).

## Events

| Event | Sent when |
| - | - |
| `interview.created` | A Candidate is added to the Interviewer |
| `interview.started` | The Candidate starts the interview |
| `interview.completed` | The Candidate finishes the interview |
| `interview.declined` | The Candidate is declined, for example by resume screening |
| `interview.opted_out` | The Candidate opts out of the interview |
| `interview.report_available` | The interview report is ready, the first time only |
| `assessment.shortlisted` | The Candidate is shortlisted for an assessment |
| `assessment.started` | The Candidate starts the assessment |
| `assessment.completed` | The Candidate finishes the assessment |

Each endpoint gets only the events it subscribed to.

## Data in each event

Every event has the same base fields. Each event then adds its own. All timestamps are ISO 8601 strings in UTC.

`metadata` gives back what you sent when you invited the Candidate, such as your ATS ID. Use it to match the event to your own record.

## interview\.created

| Field | Type | Value |
| - | - | - |
| `interviewId` | string | The Candidate's interview ID |
| `jobId` | string | The Interviewer's ID |
| `name` | string | The Candidate's name |
| `email` | string | The Candidate's email address |
| `status` | string | The Candidate's status when they were added, such as `draft`, `shortlisted` or `declined` |
| `event` | string | `interview.created` |
| `occurredAt` | string | When it happened |
| `metadata` | object or `null` | The `metadata` you sent when you invited the Candidate, or extra CSV columns. `null` if there was none |
| `createdAt` | string | When the Candidate was added. Same as `occurredAt` |

```json theme={null}
{
  "interviewId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "status": "shortlisted",
  "event": "interview.created",
  "occurredAt": "2026-11-15T10:00:00.000Z",
  "metadata": {
    "externalId": "ats-42"
  },
  "createdAt": "2026-11-15T10:00:00.000Z"
}
```

## interview\.started

| Field | Type | Value |
| - | - | - |
| `interviewId` | string | The Candidate's interview ID |
| `jobId` | string | The Interviewer's ID |
| `name` | string | The Candidate's name |
| `email` | string | The Candidate's email address |
| `status` | string | `in_progress` |
| `event` | string | `interview.started` |
| `occurredAt` | string | When it happened |
| `metadata` | object or `null` | The `metadata` you sent when you invited the Candidate, or extra CSV columns. `null` if there was none |
| `startedAt` | string | When the interview started. Same as `occurredAt` |

```json theme={null}
{
  "interviewId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "status": "in_progress",
  "event": "interview.started",
  "occurredAt": "2026-11-15T10:15:00.000Z",
  "metadata": {
    "externalId": "ats-42"
  },
  "startedAt": "2026-11-15T10:15:00.000Z"
}
```

## interview\.completed

| Field | Type | Value |
| - | - | - |
| `interviewId` | string | The Candidate's interview ID |
| `jobId` | string | The Interviewer's ID |
| `name` | string | The Candidate's name |
| `email` | string | The Candidate's email address |
| `status` | string | `completed` |
| `event` | string | `interview.completed` |
| `occurredAt` | string | When it happened |
| `metadata` | object or `null` | The `metadata` you sent when you invited the Candidate, or extra CSV columns. `null` if there was none |
| `completedAt` | string | When the interview finished. Same as `occurredAt` |
| `recordingUrl` | string or `null` | Link to the interview recording. `null` for phone interviews, or when there's no recording |

The score isn't ready yet. Wait for `interview.report_available`.

```json theme={null}
{
  "interviewId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "status": "completed",
  "event": "interview.completed",
  "occurredAt": "2026-11-15T10:35:00.000Z",
  "metadata": {
    "externalId": "ats-42"
  },
  "completedAt": "2026-11-15T10:35:00.000Z",
  "recordingUrl": "https://example.com/recording.webm"
}
```

## interview\.declined

| Field | Type | Value |
| - | - | - |
| `interviewId` | string | The Candidate's interview ID |
| `jobId` | string | The Interviewer's ID |
| `name` | string | The Candidate's name |
| `email` | string | The Candidate's email address |
| `status` | string | `declined` |
| `event` | string | `interview.declined` |
| `occurredAt` | string | When it happened |
| `metadata` | object or `null` | The `metadata` you sent when you invited the Candidate, or extra CSV columns. `null` if there was none |
| `declineReason` | string or `null` | Why the Candidate was declined, if known |
| `declinedAt` | string | When the Candidate was declined. Same as `occurredAt` |

```json theme={null}
{
  "interviewId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "status": "declined",
  "event": "interview.declined",
  "occurredAt": "2026-11-15T10:05:00.000Z",
  "metadata": {
    "externalId": "ats-42"
  },
  "declineReason": null,
  "declinedAt": "2026-11-15T10:05:00.000Z"
}
```

## interview\.opted\_out

| Field | Type | Value |
| - | - | - |
| `interviewId` | string | The Candidate's interview ID |
| `jobId` | string | The Interviewer's ID |
| `name` | string | The Candidate's name |
| `email` | string | The Candidate's email address |
| `status` | string | `opted_out` |
| `event` | string | `interview.opted_out` |
| `occurredAt` | string | When it happened |
| `metadata` | object or `null` | The `metadata` you sent when you invited the Candidate, or extra CSV columns. `null` if there was none |
| `optOutReason` | string or `null` | The reason the Candidate gave, if any |
| `optedOutAt` | string | When the Candidate opted out. Same as `occurredAt` |

```json theme={null}
{
  "interviewId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "status": "opted_out",
  "event": "interview.opted_out",
  "occurredAt": "2026-11-15T10:20:00.000Z",
  "metadata": {
    "externalId": "ats-42"
  },
  "optOutReason": "Accepted another offer",
  "optedOutAt": "2026-11-15T10:20:00.000Z"
}
```

## interview\.report\_available

Sent once, the first time the report is ready.

| Field | Type | Value |
| - | - | - |
| `interviewId` | string | The Candidate's interview ID |
| `jobId` | string | The Interviewer's ID |
| `name` | string | The Candidate's name |
| `email` | string | The Candidate's email address |
| `status` | string | The Candidate's status, usually `completed` |
| `event` | string | `interview.report_available` |
| `occurredAt` | string | When it happened |
| `metadata` | object or `null` | The `metadata` you sent when you invited the Candidate, or extra CSV columns. `null` if there was none |
| `reportGeneratedAt` | string | When the report was ready. Same as `occurredAt` |
| `overallScore` | number or `null` | The interview score out of 100 |
| `recommendation` | string or `null` | The AI recommendation shown on the report |
| `reportUrl` | string | Link to the full report in InterviewFlowAI. Your team needs to sign in to open it |
| `trustScore` | number or `null` | The trust score out of 100, from proctoring |
| `interviewFeedback` | object or `null` | The full report data, the same as the report in InterviewFlowAI |

```json theme={null}
{
  "interviewId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "status": "completed",
  "event": "interview.report_available",
  "occurredAt": "2026-11-15T10:38:00.000Z",
  "metadata": {
    "externalId": "ats-42"
  },
  "reportGeneratedAt": "2026-11-15T10:38:00.000Z",
  "overallScore": 81,
  "recommendation": "strong_yes",
  "reportUrl": "https://app.interviewflowai.com/interviewinfo?interviewId=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&jobId=9786b00b-d110-454f-9e6f-1732daec8916",
  "trustScore": 90,
  "interviewFeedback": {
    "overall_score_100": 81,
    "recommendation": "strong_yes",
    "…": "…"
  }
}
```

## assessment.shortlisted, assessment.started, assessment.completed

| Field | Type | Value |
| - | - | - |
| `interviewId` | string | The Candidate's interview ID |
| `jobId` | string | The Interviewer's ID |
| `name` | string | The Candidate's name |
| `email` | string | The Candidate's email address |
| `status` | string | See the table below |
| `event` | string | `assessment.shortlisted`, `assessment.started` or `assessment.completed` |
| `occurredAt` | string | When it happened |
| `metadata` | object or `null` | The `metadata` you sent when you invited the Candidate, or extra CSV columns. `null` if there was none |
| `assessmentScore` | number or `null` | `assessment.completed` only. The total assessment score out of 100 |
| `reportUrl` | string | `assessment.completed` only. Link to the Candidate's report in InterviewFlowAI |

| Event | `status` |
| - | - |
| `assessment.shortlisted` | `shortlisted_for_assessment` |
| `assessment.started` | `assessment_in_progress` |
| `assessment.completed` | `assessment_completed` |

```json theme={null}
{
  "interviewId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "jobId": "9786b00b-d110-454f-9e6f-1732daec8916",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "status": "assessment_completed",
  "event": "assessment.completed",
  "occurredAt": "2026-11-15T11:00:00.000Z",
  "metadata": {
    "externalId": "ats-42"
  },
  "assessmentScore": 77,
  "reportUrl": "https://app.interviewflowai.com/interviewinfo?interviewId=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&jobId=9786b00b-d110-454f-9e6f-1732daec8916"
}
```

## Zapier

[Zapier](https://docs.interviewflowai.com/platform/zapier-integration.md) gets the same data for each event.

## What can change

We only add to these events: new events and new fields. We never remove, rename or retype a field. Your code should ignore fields it doesn't know.

## Receive events

* **Respond fast.** Return a `2xx` status right away, then do slow work in the background. Failed deliveries are retried.
* **Expect duplicates.** Retries can deliver the same event more than once. A retry keeps the same `svix-id` header as the first attempt, so store the IDs you've processed and skip any you've seen before.
* **Verify the signature.** Each request carries `svix-id`, `svix-timestamp` and `svix-signature` headers, signed with your endpoint's secret (`whsec_…`). Find the secret under **Manage** on the Interviewer's **Integrations** tab, or in `webhookConfig.secret` when you create an Interviewer with the API. Verify with the [Svix libraries](https://docs.svix.com/receiving/verifying-payloads/how) before you trust the body.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.