Receiving Webhooks

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:

{
  "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 jobs will have a diarization schema as the value of the output field.
• Identify jobs will have an identify schema as the value of the output field.
• Voiceprint jobs will have a voiceprint schema as the value of the 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:

{
  "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:

{
  "jobId": "123e4567-e89b-12d3-a456-426614174000",
  "status": "canceled"
}