---
title: "Create Webhook"
method: POST
path: "/webhook"
tags: ["Webhook"]
---

# Create Webhook

`POST /webhook`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/webhook`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

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

- object
  - `callbackUrl` string, required: Give the URL Speak posts events to. required; validated as a plain string with no length cap and no uri format check
  - `events` string[]: List the events you want this webhook to receive. optional. The array carries no.required, no.optional and no min or max item count; the schema keys are optional by default. Each item must be one of the 18 listed values, which come from the WebhookEvent list. The enum applies to the array items, not to the array itself.
  - `metaData` object: Attach your own data to the webhook. Speak merges this object into the body of every delivery for this webhook, then adds eventType and deliveryId and the fields for the event that fired. optional, unconstrained object, any keys accepted. Delivery body is built as {.webhook.metaData, eventType, deliveryId } plus event fields, so a metaData key named eventType, deliveryId, state, mediaId, mediaIds, folderId, recorderId, promptId, messageId, prompt, answer, meetingAssistantId or meetingAssistantStatus is overwritten by Speak's own value.
  - `mediaId` string: Scope the webhook to a single media item instead of your whole account. optional, empty string allowed, no length cap
  - `description` string: Describe what this webhook does on your side so you can recognize it later. optional, empty string allowed, no length cap
  - `source` 'speak' | 'zapier' | 'n8n' | 'pipedream' | 'make': Say which tool is creating the webhook. Leave it out and the webhook is stored as "speak". optional; values come from the WebhookEventSource list. The schema.default('speak') is not what applies it: the controller passes source through untouched and the stored record defaults to 'speak'.

## Response `200`

OK

- object
  - `status` string
  - `data` object
    - `webhookId` string: The id of the webhook you just created. Store it, because you need it to update, test or delete the webhook.

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)