---
title: "Receive Speak AI events with outbound webhook calls"
description: "Register a webhook so Speak AI posts events to your server, list and update the webhooks on your account, send a test payload, and delete a webhook."
---

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

# Receive Speak AI events with outbound webhook calls


import EndpointIndex from "@/components/api/EndpointIndex.astro";

The Speak AI API exposes 5 webhooks endpoints under the base URL `https://api.speakai.co/v1`. Every request needs the `x-speakai-key` and `x-access-token` headers described in [Authentication](/api/authentication/).

Receive Webhooks from Speak to your platform. Manage webhook workflows and select events.

## What can you do with the webhooks endpoints?

Speak AI groups these 5 endpoints under the webhooks resource. Each entry below links to the full reference for that endpoint further down this page.

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | [`/webhook`](#get-webhook) | List |
| `POST` | [`/webhook`](#post-webhook) | Create Webhook |
| `PUT` | [`/webhook/{webhookId}`](#put-webhook-webhook-id) | Update |
| `DELETE` | [`/webhook/{webhookId}`](#delete-webhook-webhook-id) | Delete |
| `POST` | [`/webhook/test/{webhookId}`](#post-webhook-test-webhook-id) | Test |

<h2 id="get-webhook">List</h2>

If you want to list all the exisitng webhooks

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/webhook' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-webhook" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object[] |
| `data[].events` | string[] |
| `data[].isActive` | boolean |
| `data[]._id` | string |
| `data[].callbackUrl` | string |
| `data[].metaData` | object |
| `data[].description` | string |
| `data[].createdAt` | string (date-time) |

Deeper nested fields are not listed. See the example response below for the full shape.

Example response (List Webhooks), `application/json`. Arrays are shortened to one entry and long strings are cut.

```json
{
  "status": "success",
  "data": [
{
  "events": [
    "media.created"
  ],
  "isActive": true,
  "_id": "60884fec4cb70a295c0ddf59",
  "callbackUrl": "https://example.com/webhooks/speak",
  "metaData": {
    "providedInternalUUID": "111222333"
  },
  "description": "This is an edited explanation.",
  "createdAt": "2021-04-27T17:54:52.250Z"
}
  ]
}
```

</div>

</ResponsePanel>

</div>

<h2 id="post-webhook">Create Webhook</h2>

Webhooks are the means by which you receive notification in the instant event you are subscribed to is triggered. We support several media events right now:

Speak will send you a `POST` request to the webhookUrl.

We will send you related keys in the `body` params such as `mediaId`, `recorderId`, `state` , `meetingAssistantId` or `meetingAssistantStatus`

**For Media Files:**

- `media.created`

- `media.analyzed`

- `media.reanalyzed`

- `media.failed`

- `media.deleted`

**For Text Files:**

- `text.created`

    - You will receive the foll

- `text.analyzed`

    - You will receive following keys: `mediaId`, `state`

- `text.reanalyzed`

    - You will receive following keys: `mediaId`, `state`

- `text.failed`

    - You wil receive following keys: `mediaId`

- `text.deleted`

    - You will receive the following keys: `mediaId`

**For Embed Recorder:**

- `embed_recorder.created`

    - You will receive following keys: `recorderId`

- `embed_recorder.deleted`

    - You will receive following keys: `recorderId`

- `embed_recorder.recording_received`

    - You will receive following keys: `recorderId` , `mediaId`

**For Meeting Assistant:**

- `meeting_assistant.status`

    - Trigger a webhook for meeting assistant status changes for following status: Joining call, Waiting room, In call not recording, In call recording, Call ended, Error.

    - You will receive following keys: **`mediaId, meetingAssistantId`**, and **`meetingAssistantStatus`**

**For AI Chat:**

- `chat.status`

    - AI Chat response with the final answer.

    - You will receive follwoing keys: `mediaIds, folderId, state, promptId, messageId and answer`

**For CSV Files:**

- `csv.uploaded`

    - When you upload the CSV file, it will return with `fileId, totalRecords, succeededRecords`

- `csv.failed`

    - When there is a failure or few records failed, you will receive fileId  
        `fileId, totalRecords, failedRecords, failedRecordsList`

You can subscribe to one or more events at once for one media, and then later update your webhook as needed.  
Internally, Speak AI system will `POST` to `callbackURL` with provided `metaData` as a request body, the attempt will be recorded and you can access the results, errors and response times in [https://app.speakai.co/developers/webhooks](https://app.speakai.co/developers/webhooks)

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `callbackUrl` | string |
| `metaData` | object |
| `metaData.providedInternalUUID` | string |
| `events` | string[] |
| `description` | string |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/webhook' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "callbackUrl": "https://example.com/webhooks/speak",
  "metaData": {
"providedInternalUUID": "111222333"
  },
  "events": [
"media.created",
"media.analyzed",
"text.created",
"text.analyzed",
"text.reanalyzed",
"text.failed",
"text.deleted",
"media.reanalyzed",
"media.failed",
"media.deleted"
  ],
  "description": "This is a readable explanation of what this webhook does on your side."
}'
```

</CodePanel>

<ResponsePanel id="post-webhook" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.events` | string[] |
| `data.attempts` | any[] |
| `data.isActive` | boolean |
| `data.isDeleted` | boolean |
| `data._id` | string |
| `data.companyId` | string |
| `data.userId` | string |
| `data.callbackUrl` | string |
| `data.metaData` | object |
| `data.description` | string |
| `data.createdAt` | string (date-time) |
| `data.__v` | integer |

Deeper nested fields are not listed. See the example response below for the full shape.

Example response (Success), `application/json`. Arrays are shortened to one entry and long strings are cut.

```json
{
  "status": "success",
  "data": {
"events": [
  "media.created"
],
"attempts": [],
"isActive": true,
"isDeleted": false,
"_id": "608850ed4cb70a295c0ddf5b",
"companyId": "5e21c8dd2d77242c64214816",
"userId": "5d03a9d5d4bca272e9c8cf89",
"callbackUrl": "https://example.com/webhooks/speak",
"metaData": {
  "providedInternalUUID": "111222333"
},
"description": "This is a readable explanation of what this webhook does on your side.",
"createdAt": "2021-04-27T17:59:09.862Z",
"__v": 0
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="put-webhook-webhook-id">Update</h2>

You can update definition of an existing webhook: change events it's subscribed to, edit description or your `metaData`.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookId` | path | string | Yes |  |

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `callbackUrl` | string |
| `metaData` | object |
| `metaData.providedInternalUUID` | string |
| `events` | string[] |
| `description` | string |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X PUT 'https://api.speakai.co/v1/webhook/609d7de35bde285f4c98ca63' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "callbackUrl": "https://example.com/webhooks/speak",
  "metaData": {
"providedInternalUUID": "777888999"
  },
  "events": [
"media.created",
"media.analyzed",
"media.deleted"
  ],
  "description": "This is an edited explanation."
}'
```

</CodePanel>

<ResponsePanel id="put-webhook-webhook-id" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `message` | string |

Example response (Successful), `application/json`.

```json
{
  "status": "success",
  "message": "Webhook updated"
}
```

</div>

</ResponsePanel>

</div>

<h2 id="delete-webhook-webhook-id">Delete</h2>

#### DELETE Webhook

This endpoint allows you to delete a specific webhook identified by its unique `webhookId`.

##### Request Parameters

- `webhookId` (path parameter): The unique identifier of the webhook you wish to delete.

##### Expected Response

Upon successful deletion of the webhook, the API will return a JSON object with the following structure:

- `status`: A string indicating the status of the request.

- `message`: A string providing additional information about the result of the operation.

##### Notes

- Ensure that the `webhookId` provided in the request is valid and corresponds to an existing webhook.

- Deleting a webhook is irreversible; once deleted, the webhook cannot be recovered.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookId` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X DELETE 'https://api.speakai.co/v1/webhook/609d7de35bde285f4c98ca63' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="delete-webhook-webhook-id" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `message` | string |

Example response (Success), `application/json`.

```json
{
  "status": "success",
  "message": "Webhook deleted!"
}
```

</div>

</ResponsePanel>

</div>

<h2 id="post-webhook-test-webhook-id">Test</h2>

Looking to test the webhook without uploading much media in your account ? Testing is made easier using this endpoint. You can trigger an event on a particular webhook and get the request\response or error.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhookId` | path | string | Yes |  |

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `event` | string |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/webhook/test/659ee5c7350d7f6593fd36ea' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "event": "media.created"
}'
```

</CodePanel>

<ResponsePanel id="post-webhook-test-webhook-id" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.isFirstAttempt` | boolean |
| `data._id` | string |
| `data.webhookId` | string |
| `data.event` | string |
| `data.requestBody` | string |
| `data.responseBody` | string |
| `data.responseTime` | integer |
| `data.createdAt` | string (date-time) |
| `data.__v` | integer |

Example response (Success), `application/json`.

```json
{
  "status": "success",
  "data": {
"isFirstAttempt": true,
"_id": "608854d7368c102ad3d3ad53",
"webhookId": "60884fec4cb70a295c0ddf59",
"event": "media.created",
"requestBody": "{\"providedInternalUUID\":\"111222333\"}",
"responseBody": "{\"message\":\"My UUID is 111222333.\"}",
"responseTime": 48,
"createdAt": "2021-04-27T18:15:51.686Z",
"__v": 0
  }
}
```

Example response (Error), `application/json`.

```json
{
  "status": "success",
  "data": {
"isFirstAttempt": true,
"_id": "608854d7368c102ad3d3ad53",
"webhookId": "60884fec4cb70a295c0ddf59",
"event": "media.created",
"requestBody": "{\"providedInternalUUID\":\"111222333\"}",
"responseBody": "{\"message\":\"invalid json response body at https://example.com/webhooks/speak reason: Unexpected token < in JSON at position 0\",\"type\":\"invalid-json\"}",
"responseTime": 48,
"createdAt": "2021-04-27T18:15:51.686Z",
"__v": 0
  }
}
```

</div>

</ResponsePanel>

</div>

## Related pages

- [API reference](/api/) for the base URL, authentication, and the error format.
- [Authenticate with the Speak AI API using access tokens](/api/authentication/)
- [Upload audio and video to Speak AI and read insights](/api/media/)
- [Create and update live transcription sessions in Speak AI](/api/live-transcription/)
- [Analyze text notes with the Speak AI text endpoints](/api/text/)

Get an API key on the [Speak AI developer page](https://app.speakai.co/developers?utm_source=docs&utm_medium=referral&utm_campaign=api-reference&utm_content=api-webhooks).

Source: https://docs.speakai.co/api/webhooks/index.mdx