Skip to main content
pyannoteAI can send an HTTP POST request to a specified URL when a job is completed. To receive webhooks, you must specify a webhook URL in the webhook field when creating a diarization, identify or voiceprint job. 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 failed or was canceled, the status field will be canceled and there will be no output field.

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