Receive Speak AI events with outbound webhook calls

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.

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.

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.

List

GET/webhook

If you want to list all the exisitng webhooks

Example request

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'

Response

200 OK

Response body, application/json.

Field	Type	Description
`status`	string
`data`	object
`data.totalCount`	integer	How many webhooks you have in total, so you can page through them.
`data.webhooks`	object[]

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.

{
  "status": "success",
  "data": {
    "totalCount": 1,
    "webhooks": [
      {
        "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"
      }
    ]
  }
}

Create Webhook

POST/webhook

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

Request body

Fields marked required are the ones the server rejects the request without. Anything conditional, where a field becomes required only alongside another, is described under Request rules above rather than marked here.

Field	Type	Description
`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. One of: `embed_recorder.created`, `embed_recorder.deleted`, `embed_recorder.recording_received`, `media.analyzed`, `media.created`, `media.deleted`, `media.failed`, `media.reanalyzed`, `media.updated`, `text.analyzed`, `text.created`, `text.deleted`, `text.failed`, `text.reanalyzed`, `meeting_assistant.status`, `chat.status`, `csv.uploaded`, `csv.failed`.
`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`	string	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’. One of: `speak`, `zapier`, `n8n`, `pipedream`, `make`.

Example request

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."
}'

Response

200 OK

Response body, application/json.

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

Example response (Success), application/json.

{
  "status": "success",
  "data": {
    "webhookId": "608850ed4cb70a295c0ddf5b"
  }
}

Update

PUT/webhook/{webhookId}

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	Type	Description
`callbackUrl`	string, required	Give the URL Speak posts events to. Send it on every update, even when you are only changing something else. required; validated as a plain string with no length cap and no uri format check
`metaData`	object	Replace the data Speak merges into the body of every delivery for this webhook. Speak adds eventType, deliveryId and the fields for the event that fired on top of it. optional, unconstrained object, any keys accepted. Omitting it writes undefined over the stored value, because the controller passes the destructured value straight into findOneAndUpdate.
`mediaId`	string	Scope the webhook to a single media item instead of your whole account. optional, empty string allowed, no length cap
`events`	string[]	Replace the list of events this webhook receives. explicitly.optional; no minimum or maximum item count. Each item must be one of the 18 listed values, which come from WebhookEvent. One of: `embed_recorder.created`, `embed_recorder.deleted`, `embed_recorder.recording_received`, `media.analyzed`, `media.created`, `media.deleted`, `media.failed`, `media.reanalyzed`, `media.updated`, `text.analyzed`, `text.created`, `text.deleted`, `text.failed`, `text.reanalyzed`, `meeting_assistant.status`, `chat.status`, `csv.uploaded`, `csv.failed`.
`description`	string	Describe what this webhook does on your side so you can recognize it later. optional, empty string allowed, no length cap

Example request

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."
}'

Response

200 OK

Response body, application/json.

Field	Type
`status`	string
`message`	string

Example response (Successful), application/json.

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

Delete

DELETE/webhook/{webhookId}

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

Example request

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'

Response

200 OK

Response body, application/json.

Field	Type
`status`	string
`message`	string

Example response (Success), application/json.

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

Test

POST/webhook/test/{webhookId}

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	Type	Description
`event`	string, required	Pick the event to fire so you can see the request, the response and any error your endpoint returns. required; the 18 values come from the WebhookEvent list. No other body key is accepted, so any extra property returns a 400. One of: `embed_recorder.created`, `embed_recorder.deleted`, `embed_recorder.recording_received`, `media.analyzed`, `media.created`, `media.deleted`, `media.failed`, `media.reanalyzed`, `media.updated`, `text.analyzed`, `text.created`, `text.deleted`, `text.failed`, `text.reanalyzed`, `meeting_assistant.status`, `chat.status`, `csv.uploaded`, `csv.failed`.

Example request

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"
}'

Response

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.

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

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

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

Get an API key on the Speak AI developer page.

Receive Speak AI events with outbound webhook calls

What can you do with the webhooks endpoints?

List

Create Webhook

Request body

Update

Parameters

Request body

Delete

DELETE Webhook

Request Parameters

Expected Response

Notes

Parameters

Test

Parameters

Request body

Related pages