Skip to content
SpeakDocs

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.

Updated View as MarkdownAsk ClaudeOpen in ChatGPTllms.txt

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

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

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

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

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

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

Get an API key on the Speak AI developer page.

Navigation
All sections

Type to search…

↑↓ navigate↵ selectEsc close