> ## Documentation Index
> Fetch the complete documentation index at: https://assembly-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Webhooks are custom HTTP callbacks that you can define to get notified when your transcripts are ready

To use webhooks, you need to set up your own webhook receiver to handle webhook deliveries.

## Create a webhook for a transcription

To create a webhook, use `set_webhook()` on the transcription config. The URL must be accessible from AssemblyAI's servers.

Use `submit()` instead of `transcribe()` to create a transcription without waiting for it to complete.

<CodeGroup>
  ```python Python theme={"system"}
  import assemblyai as aai

  aai.settings.api_key = "YOUR_API_KEY"

  # audio_file = "./local_file.mp3"
  audio_file = "https://assembly.ai/wildfires.mp3"

  config = aai.TranscriptionConfig().set_webhook("https://example.com/webhook")

  aai.Transcriber().submit(audio_file, config)
  ```

  ```typescript Typescript theme={"system"}
  import { AssemblyAI } from 'assemblyai'

  const client = new AssemblyAI({
    apiKey: 'YOUR_API_KEY'
  })

  // const audioFile = './local_file.mp3'
  const audioFile =
    'https://assembly.ai/wildfires.mp3'

  client.transcripts.submit({
    audio: audioFile,
    webhook_url: 'https://example.com/webhook'
  })
  ```

  ```go Go theme={"system"}
  package main

  import (
      "context"

      aai "github.com/AssemblyAI/assemblyai-go-sdk"
  )

  func main() {
      ctx := context.Background()

      client := aai.NewClient("YOUR_API_KEY")

      // For local files see our Getting Started guides.
      audioURL := "https://assembly.ai/wildfires.mp3"

      _, _ = client.Transcripts.SubmitFromURL(ctx, audioURL, &aai.TranscriptOptionalParams{
          WebhookURL:             aai.String("https://example.com/webhook"),
      })
  }
  ```

  ```java Java theme={"system"}
  import com.assemblyai.api.AssemblyAI;
  import com.assemblyai.api.resources.transcripts.types.*;

  public final class App {
      public static void main(String... args) {
          AssemblyAI client = AssemblyAI.builder()
                  .apiKey("YOUR_API_KEY")
                  .build();

          // For local files see our Getting Started guides.
          String audioUrl = "https://assembly.ai/wildfires.mp3";

          var params = TranscriptOptionalParams.builder()
                  .webhookUrl("https://example.com/webhook")
                  .build();

          Transcript transcript = client.transcripts().submit(audioUrl, params);
      }
  }
  ```

  ```csharp C# theme={"system"}
  using AssemblyAI;
  using AssemblyAI.Transcripts;

  var client = new AssemblyAIClient("YOUR_API_KEY");

  // For local files see our Getting Started guides.
  const string audioUrl = "https://assembly.ai/wildfires.mp3";

  var transcriptParams = new TranscriptParams
  {
      AudioUrl = audioUrl,
      WebhookUrl = "https://example.com/webhook"
  };

  var transcript = await client.Transcripts.SubmitAsync(transcriptParams);
  ```

  ```ruby Ruby theme={"system"}
  require 'assemblyai'

  client = AssemblyAI::Client.new(api_key: 'YOUR_API_KEY')

  # For local files see our Getting Started guides.
  audio_url = 'https://assembly.ai/sports_injuries.mp3'

  transcript = client.transcripts.submit(
    audio_url: audio_url,
    webhook_url: 'https://example.com/webhook'
  )
  ```
</CodeGroup>

## Handle webhook deliveries

When the transcript is ready, AssemblyAI will send a `POST` HTTP request to the URL that you specified.

<Info>
  Sender's IP address

  AssemblyAI sends all webhook deliveries from the same IP address, 44.238.19.20.
</Info>

### Delivery payload

The webhook delivery payload contains a JSON object with the following properties:

```js theme={"system"}
{transcript_id:"5552493-16d8-42d8-8feb-c2a16b56f6e8",status:"completed"}
```

| Key             | Type   | Description                                                  |
| --------------- | ------ | ------------------------------------------------------------ |
| `transcript_id` | string | The ID of the transcript.                                    |
| `status`        | string | The status of the transcript. Either `completed` or `error`. |

## Authenticate webhook deliveries

You can authenticate webhook deliveries from AssemblyAI by including a custom HTTP header in the request.

To add an authentication header, include the auth header name and value in `set_webhook()`.

<CodeGroup>
  ```python Python theme={"system"}
  config = aai.TranscriptionConfig().set_webhook(
      "https://example.com/webhook", "X-My-Webhook-Secret", "secret-value"
  )

  aai.Transcriber().submit(audio_url, config)
  ```

  ```typescript Typescript theme={"system"}
  client.transcripts.submit({
    audio:
      'https://assembly.ai/wildfires.mp3',
    webhook_url: 'https://example.com/webhook'
    webhook_auth_header_name: "X-My-Webhook-Secret",
    webhook_auth_header_value: "secret-value"
  })
  ```

  ```go Go theme={"system"}
  client.Transcripts.SubmitFromURL(ctx, audioURL, &aai.TranscriptOptionalParams{
      WebhookURL:             aai.String("https://example.com/webhook"),
      WebhookAuthHeaderName:  aai.String("X-My-Webhook-Secret"),
      WebhookAuthHeaderValue: aai.String("secret-value"),
  })
  ```

  ```java Java theme={"system"}
  var params = TranscriptOptionalParams.builder()
          .webhookUrl("https://example.com/webhook")
          .webhookAuthHeaderName("X-My-Webhook-Secret")
          .webhookAuthHeaderValue("secret-value")
          .build();
  ```

  ```csharp C# theme={"system"}
  var transcriptParams = new TranscriptParams
  {
      AudioUrl = audioUrl,
      WebhookUrl = "https://example.com/webhook",
      WebhookAuthHeaderName = "X-My-Webhook-Secret",
      WebhookAuthHeaderValue = "secret-value"
  };
  ```

  ```ruby Ruby theme={"system"}
  transcript = client.transcripts.submit(
    audio_url: audio_url,
    webhook_url: 'https://example.com/webhook',
    webhook_auth_header_value: 'X-My-Webhook-Secret',
    webhook_auth_header_name: 'secret-value'
  )
  ```
</CodeGroup>

## Add metadata to webhook deliveries

To associate metadata for a specific transcription request, you can add your own query parameters to the webhook URL.

```sh theme={"system"}
https://example.com/webhook?customer_id=1234&order_id=5678
```

Now, when you receive the webhook delivery, you'll know the customer who requested it.

## Handling failed webhook deliveries

Webhook deliveries can fail for multiple reasons. For example, if your server is down or takes more than 10 seconds to respond.

If a webhook delivery fails, AssemblyAI will attempt to redeliver it up to 10 times, waiting 10 seconds between each attempt. If all attempts fail, AssemblyAI considers the delivery as permanently failed.

<Tip>
  `submit()` returns an object with the ID of the transcription. If the webhook delivery fails, you can use this ID to retrieve the transcript later.
</Tip>