Skip to main content
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, identify or 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:
Request body
{
  "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.
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.

​
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:
Request body
{
  "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:
Request body
{
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "failed"
}
For a canceled job, the webhook payload will look like the following:
Request body
{
  "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:
Request body
{
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "succeeded"
}