POST Webhooks

Create or Replace Webhook

Timeouts for Webhooks Webhooks must complete within the allowed time 3 seconds or it is considered a timeout If your webhook consistently times out or fails to return with a suc…

POST /api/v3/{appid}/webhook/hooks

Requires Authentication.

Timeouts for Webhooks

Webhooks must complete within the allowed time (3 seconds) or it is considered a timeout
If your webhook consistently times out or fails to return with a success code then it may be deactivated
Your webhook should receive the event and return immediately

PROPERTIES

label : (required) A unique string for your webhook. It can be anything you want.
url: (required) A URL to post to when the webhook is activated.
enabled: (required) Sets the webhook to be in either the enabled or disabled states.
type: (required) ["prepublish"/"postpublish"] Sets the type of webhook. See TYPES below.
events: (required) An array of strings indicating which event types activate your webhook. See events below for allowed values.
requireallcustomtags: (optional) An array of strings indicating required tags. If any of the required tags are not present as custom tags on the room or conversation triggering the webhook then the webhook will not be fired.

BEHAVIOR: CREATE OR UPDATE

If the label is already in use by a webhook in the system, this will re-create the webhook, replacing what is in the database with the new settings you passed in.

WEBHOOK TYPES

There are two types of webhook: prepublish and postpublish.

Pre-Publish Webhook

Pass "prepublish" for the type parameter to create this type of webhook. This webhook will fire before the event is fired. If the remote system responds with 200 then the message will continue through the pipeline to be published. If you have more than one prepublish webhook, if any respond with other than 200 the message will be blocked. An example of when you would use a pre-publish webhook is when you want to perform pre-moderation with an external system.

Post-Publish Webhook

Pass "postpublish" for the type parameter to create this type of webhook. This webhook will fire after an event is published. The reponse from the remote service is ignored. An example of a post publish webhook would be using post moderation with an external system.

EVENT TYPES

The following event types are supported.

chatcustom
chatspeech
chatquote
chatreply
chatreaction
chataction
chatenter
chatexit
chatroomopened
chatroomclosed
chatpurge
commentpublished
commentreply

Request

Parameters

Values in the path and query string.

appid path

string TalkLabs ID required

The TalkLabs application ID assigned to your account.

Example: your-app-id

Request

JSON body

Send as application/json.

label

string required

url

string required

enabled

boolean required

webhookType

integer · int32 required

events

WebhookEventTypes[] required

entities

string[]

requiredCustomTags

string[]

Request example

{
  "label": "Demonstration Webhook (prepublish)",
  "url": "https://localhost:443",
  "enabled": false,
  "events": [
    "commentpublished",
    "commentreply"
  ],
  "webhookType": {}
}

Request examples

Common variations

Historical examples filtered through the current request schema.

Create or Replace Webhook (prepublish)

{
  "label": "Demonstration Webhook (prepublish)",
  "url": "https://localhost:443",
  "enabled": false,
  "events": [
    "commentpublished",
    "commentreply"
  ],
  "webhookType": {}
}

Create or Replace Webhook (postpublish)

{
  "label": "Demonstration Webhook (postpublish chatspeech)",
  "url": "https://webhook.site/#!/752e6569-13b6-4933-b5e5-960084592da9",
  "enabled": true,
  "events": [
    "chatspeech"
  ],
  "webhookType": {}
}

Response

Status codes

Every JSON response uses the API result envelope.

200 OK ApiResult

400 Bad Request ApiResult

403 Forbidden ApiResult

500 Internal Server Error ApiResult

curl --request POST \
  --url "https://api.sportstalk247.com/api/v3/${APP_ID}/webhook/hooks" \
  --header "Accept: application/json" \
  --header "x-api-token: ${TALKLABS_API_TOKEN}" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "label": "Demonstration Webhook (prepublish)",
  "url": "https://localhost:443",
  "enabled": false,
  "events": [
    "commentpublished",
    "commentreply"
  ],
  "webhookType": {}
}'

const appId = process.env.TALKLABS_APP_ID;


const response = await fetch(
  `https://api.sportstalk247.com/api/v3/${appId}/webhook/hooks`,
{
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'x-api-token': process.env.TALKLABS_API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "label": "Demonstration Webhook (prepublish)",
  "url": "https://localhost:443",
  "enabled": false,
  "events": [
    "commentpublished",
    "commentreply"
  ],
  "webhookType": {}
}),
});

const result = await response.json();

import json
import os
import requests

app_id = os.environ["TALKLABS_APP_ID"]


response = requests.post(
    f"https://api.sportstalk247.com/api/v3/{app_id}/webhook/hooks",
    headers={
        "Accept": "application/json",
        "x-api-token": os.environ["TALKLABS_API_TOKEN"],
    },
    json=json.loads(r'''{
  "label": "Demonstration Webhook (prepublish)",
  "url": "https://localhost:443",
  "enabled": false,
  "events": [
    "commentpublished",
    "commentreply"
  ],
  "webhookType": {}
}'''),
)
response.raise_for_status()
result = response.json()

Environment variables TALKLABS_APP_ID TALKLABS_API_TOKEN

Response