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

# Receiving Webhooks

pyannoteAI can send an HTTP POST request to a specified URL when a job reaches a terminal status.

To receive webhooks, you must specify a webhook URL in the `webhook` field when
creating a [diarization](/api-reference/diarize), [identify](/api-reference/identify)
or [voiceprint](/api-reference/voiceprint) job.

You can also set `webhookStatusOnly` to `true` when creating the job (default:
`false`). When this option is enabled, webhook payloads only include `jobId`
and `status` (the `output` field is excluded), which is useful for large
payloads.

Webhooks are sent when the job status is one of:

* `succeeded`
* `failed`
* `canceled`

Webhooks are not sent for `pending`, `created`, or `running` statuses.

The request body will be a JSON object containing job data. Here's an example of what the request body will look like for a succeeded diarization job:

```json Request body theme={null}
{
  "jobId": "job_id",
  "status": "succeeded",
  "output": {
    "diarization": [
      {
        "start": 0.0,
        "end": 1.0,
        "speaker": "speaker_1"
      }
      ...
    ]
  }
}
```

The `output` field will be different depending on the type of job you created.

* [Diarization](/api-reference/diarize) jobs will have a [diarization schema](/api-reference/schemas/diarizationschema) as the value of the `output` field.
* [Identify](/api-reference/identify) jobs will have an [identify schema](/api-reference/schemas/identifyschema) as the value of the `output` field.
* [Voiceprint](/api-reference/voiceprint) jobs will have a [voiceprint schema](/api-reference/schemas/voiceprintschema) as the value of the `output` field.

<Info>
  If a job fails, the `status` field will be `failed` and there will be no
  `output` field. If a job is canceled, the `status` field will be `canceled`
  and there will be no `output` field. If `webhookStatusOnly` is `true`, there
  will be no `output` field for any status, including `succeeded`.
</Info>

## Retries

pyannoteAI will retry sending the webhook up to 3 times. The first retry is immediate, the second retry after 1 minute, and the third retry after 5 minutes.

With each retry attempt, you'll also be given a `x-retry-num` HTTP header indicating the attempt number: `1`, `2`, or `3`.

An attempt will be considered unsuccessful if your webhook doesn't behave as expected.
This will be communicated to you in the `x-retry-reason` HTTP header, where you'll find a string describing the reason why the previous attempt failed.

Here is a list of all the possible failure codes and their reason:

* `http_timeout`: We didn't receive a response from your server within 10 seconds.
* `too_many_redirects`: The request was redirected more than twice.
* `connection_failed`: We couldn't connect to your server.
* `ssl_error`: We couldn't verify the authenticity of your SSL certificate.
* `http_error`: Your server responded with an HTTP status code that was not in the HTTP 200 OK range.
* `unknown_error`: We encountered an unknown error.

## Example webhook payloads

For a successful diarization job, the webhook payload will look like the following:

```json Request body theme={null}
{
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "succeeded",
  "output": {
    "diarization": [
      {
        "start": 0.0,
        "end": 1.0,
        "speaker": "speaker_1"
      }
      ...
    ]
  }
}
```

For a failed job, the webhook payload will look like the following:

```json Request body theme={null}
{
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "failed"
}
```

For a canceled job, the webhook payload will look like the following:

```json Request body theme={null}
{
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "canceled"
}
```

When you create a job with `webhookStatusOnly: true`, the webhook payload will
look like the following even if the job succeeded:

```json Request body theme={null}
{
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "succeeded"
}
```