Configurar webhook

Crear webhook

curl --request POST \
  --url https://api-prod.studio.getsupervisor.ai/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-workspace-id: <x-workspace-id>' \
  --data '
{
  "url": "<string>",
  "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "description": "<string>",
  "isActive": true,
  "headers": {},
  "secret": "<string>",
  "method": "POST"
}
'

import requests

url = "https://api-prod.studio.getsupervisor.ai/v1/webhooks"

payload = {
    "url": "<string>",
    "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "description": "<string>",
    "isActive": True,
    "headers": {},
    "secret": "<string>",
    "method": "POST"
}
headers = {
    "x-workspace-id": "<x-workspace-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-workspace-id': '<x-workspace-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: '<string>',
    agentId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    description: '<string>',
    isActive: true,
    headers: {},
    secret: '<string>',
    method: 'POST'
  })
};

fetch('https://api-prod.studio.getsupervisor.ai/v1/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-prod.studio.getsupervisor.ai/v1/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => '<string>',
    'agentId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'description' => '<string>',
    'isActive' => true,
    'headers' => [
        
    ],
    'secret' => '<string>',
    'method' => 'POST'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-workspace-id: <x-workspace-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-prod.studio.getsupervisor.ai/v1/webhooks"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"agentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"description\": \"<string>\",\n  \"isActive\": true,\n  \"headers\": {},\n  \"secret\": \"<string>\",\n  \"method\": \"POST\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-workspace-id", "<x-workspace-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-prod.studio.getsupervisor.ai/v1/webhooks")
  .header("x-workspace-id", "<x-workspace-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"<string>\",\n  \"agentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"description\": \"<string>\",\n  \"isActive\": true,\n  \"headers\": {},\n  \"secret\": \"<string>\",\n  \"method\": \"POST\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-prod.studio.getsupervisor.ai/v1/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-workspace-id"] = '<x-workspace-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"<string>\",\n  \"agentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"description\": \"<string>\",\n  \"isActive\": true,\n  \"headers\": {},\n  \"secret\": \"<string>\",\n  \"method\": \"POST\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "url": "<string>",
  "isActive": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "description": "<string>",
  "method": "POST",
  "secretPreview": "<string>",
  "lastDeliveryAt": "2023-11-07T05:31:56Z",
  "headers": {},
  "successCount": 1,
  "failureCount": 1
}

POST

webhooks

Crear webhook

curl --request POST \
  --url https://api-prod.studio.getsupervisor.ai/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-workspace-id: <x-workspace-id>' \
  --data '
{
  "url": "<string>",
  "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "description": "<string>",
  "isActive": true,
  "headers": {},
  "secret": "<string>",
  "method": "POST"
}
'

import requests

url = "https://api-prod.studio.getsupervisor.ai/v1/webhooks"

payload = {
    "url": "<string>",
    "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "description": "<string>",
    "isActive": True,
    "headers": {},
    "secret": "<string>",
    "method": "POST"
}
headers = {
    "x-workspace-id": "<x-workspace-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-workspace-id': '<x-workspace-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: '<string>',
    agentId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    description: '<string>',
    isActive: true,
    headers: {},
    secret: '<string>',
    method: 'POST'
  })
};

fetch('https://api-prod.studio.getsupervisor.ai/v1/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-prod.studio.getsupervisor.ai/v1/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'url' => '<string>',
    'agentId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'description' => '<string>',
    'isActive' => true,
    'headers' => [
        
    ],
    'secret' => '<string>',
    'method' => 'POST'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-workspace-id: <x-workspace-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-prod.studio.getsupervisor.ai/v1/webhooks"

	payload := strings.NewReader("{\n  \"url\": \"<string>\",\n  \"agentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"description\": \"<string>\",\n  \"isActive\": true,\n  \"headers\": {},\n  \"secret\": \"<string>\",\n  \"method\": \"POST\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-workspace-id", "<x-workspace-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-prod.studio.getsupervisor.ai/v1/webhooks")
  .header("x-workspace-id", "<x-workspace-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"<string>\",\n  \"agentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"description\": \"<string>\",\n  \"isActive\": true,\n  \"headers\": {},\n  \"secret\": \"<string>\",\n  \"method\": \"POST\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-prod.studio.getsupervisor.ai/v1/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-workspace-id"] = '<x-workspace-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"<string>\",\n  \"agentId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"description\": \"<string>\",\n  \"isActive\": true,\n  \"headers\": {},\n  \"secret\": \"<string>\",\n  \"method\": \"POST\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "url": "<string>",
  "isActive": true,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "agentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "description": "<string>",
  "method": "POST",
  "secretPreview": "<string>",
  "lastDeliveryAt": "2023-11-07T05:31:56Z",
  "headers": {},
  "successCount": 1,
  "failureCount": 1
}

Crea un webhook para recibir eventos de telefonía como call.status.updated, call.completed y call.error. La URL debe aceptar peticiones HTTPS.

Incluye X-API-Key y el header X-Workspace-Id al crear el webhook. El servicio puede firmar cada evento con X-Supervisor-Signature si proporcionas un secret.

Crear un webhook

import { createClient } from "@getsupervisor/agents-studio-sdk";

const client = createClient({
baseUrl: process.env.API_BASE_URL!,
workspaceId: process.env.WORKSPACE_ID!,
apiKey: process.env.API_KEY!,
});

const webhook = await client.webhooks.create({
url: "https://miapp.com/webhooks/supervisor",
description: "Actualiza el CRM con el estado de la llamada",
headers: {
"X-Custom-Signature": "allowed",
},
isActive: true,
});

console.log(webhook.id, webhook.secretPreview);

curl --request POST \
  --url "$API_BASE_URL/v1/webhooks" \
  --header "X-API-Key: $API_KEY" \
  --header "X-Workspace-Id: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://miapp.com/webhooks/supervisor",
    "description": "Actualiza el CRM con el estado de la llamada",
    "headers": {
      "X-Custom-Signature": "allowed"
    },
    "isActive": true
  }'

Respuesta 201 Created

{
  "id": "wh_01J8XW1N9P2Q3R4S5T6U",
  "agentId": null,
  "url": "https://miapp.com/webhooks/supervisor",
  "description": "Actualiza el CRM con el estado de la llamada",
  "isActive": true,
  "secretPreview": "whsec_********************",
  "createdAt": "2025-08-19T16:00:00.000Z",
  "updatedAt": "2025-08-19T16:00:00.000Z",
  "lastDeliveryAt": null,
  "headers": {
    "X-Custom-Signature": "allowed"
  },
  "successCount": 0,
  "failureCount": 0
}

Si no envías secret, generaremos uno aleatorio de 32 caracteres. Para asociar el webhook a un agente de voz agrega agentId en el cuerpo.

Suscribirse a eventos

Una vez creado el webhook tienes que registrar las suscripciones que definen qué eventos se entregarán. Usa el endpoint POST /v1/webhooks//subscriptions con las claves del catálogo de eventos (por ejemplo call.status.updated, call.completed, call.error).

import { createClient } from "@getsupervisor/agents-studio-sdk";

const client = createClient({
baseUrl: process.env.API_BASE_URL!,
workspaceId: process.env.WORKSPACE_ID!,
apiKey: process.env.API_KEY!,
});

const subscription = await client.webhooks.createSubscription(
"wh_01J8XW1N9P2Q3R4S5T6U",
{
eventKey: "call.status.updated",
isActive: true,
}
);

console.log(subscription.id, subscription.eventKey);

curl --request POST \
  --url "$API_BASE_URL/v1/webhooks/wh_01J8XW1N9P2Q3R4S5T6U/subscriptions" \
  --header "X-API-Key: $API_KEY" \
  --header "X-Workspace-Id: $WORKSPACE_ID" \
  --header "Content-Type: application/json" \
  --data '{
    "eventKey": "call.status.updated",
    "isActive": true
  }'

Respuesta 201 Created

{
  "id": "sub_01J8XY7Z8A9B0C1D2E3F",
  "eventKey": "call.status.updated",
  "isActive": true,
  "webhookId": "wh_01J8XW1N9P2Q3R4S5T6U",
  "createdAt": "2025-08-19T16:00:05.000Z",
  "updatedAt": "2025-08-19T16:00:05.000Z"
}

Puedes crear varias suscripciones por webhook, una por eventKey. Si envías una clave no registrada en el catálogo recibirás 400. Usa GET /v1/webhooks//subscriptions para listar las suscripciones activas.

Notificaciones que enviaremos

Publicaremos eventos a tu URL en formato JSON. Incluimos ejemplos típicos:

call.status.updated — registrada

{
  "id": "evt_01J7W8A4XK0N5Y6Z7Q8P",
  "type": "call.status.updated",
  "created_at": "2025-08-19T16:01:00.000Z",
  "data": {
    "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
    "call_status": "registered",
    "direction": "outbound",
    "to_number": "+525538808448"
  }
}

call.status.updated — en curso

{
  "id": "evt_01J7W8A5A1B2C3D4E5F6",
  "type": "call.status.updated",
  "created_at": "2025-08-19T16:01:10.000Z",
  "data": {
    "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
    "call_status": "ongoing",
    "from_number": "+12137771234",
    "to_number": "+525538808448",
    "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"
  }
}

call.status.updated — finalizada

{
  "id": "evt_01J7W8A6G7H8I9J0K1L2",
  "type": "call.status.updated",
  "created_at": "2025-08-19T16:05:00.000Z",
  "data": {
    "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
    "call_status": "ended",
    "disconnection_reason": "agent_hangup",
    "duration_ms": 10000,
    "recording_url": "https://example.com/recording.wav",
    "public_log_url": "https://example.com/public_log.txt"
  }
}

call.status.updated — error

{
  "id": "evt_01J7W8A7M8N9O0P1Q2R3",
  "type": "call.status.updated",
  "created_at": "2025-08-19T16:02:00.000Z",
  "data": {
    "call_id": "Jabr9TXYYJHfvl6Syypi88rdAHYHmcq6",
    "call_status": "error",
    "error_code": "telephony_provider_unavailable",
    "error_message": "Carrier unavailable"
  }
}

Validación de firmas (opcional)

Si configuras secret, firmaremos cada notificación con HMAC-SHA256 en el header X-Supervisor-Signature usando el formato sha256=HEX.

Reintentos y respuestas

Esperamos 2xx de tu servidor. Si no, reintentaremos con backoff.
Responde 200 OK lo antes posible (procesa de forma asíncrona si es necesario).

Buenas prácticas

Usa colas para procesar eventos.
Idempotencia: guarda id del evento para evitar duplicados.
Verifica la firma si definiste secret.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-workspace-id

string<uuid>

required

Identificador del workspace multi-tenant.

Body

application/json

url

string<uri>

required

Debe ser https.

agentId

string<uuid> | null

Identificador del agente asociado cuando aplica.

description

string | null

Maximum string length: 500

isActive

boolean

default:true

headers

object

Show child attributes

secret

string

Secreto HMAC opcional proporcionado por el cliente. Si se omite, el backend genera uno.

method

enum<string>

default:POST

Método HTTP para entregar eventos del webhook

Available options:

GET,

POST

Response

Created

string<uuid>

required

url

string<uri>

required

Debe ser https.

isActive

boolean

required

createdAt

string<date-time>

required

updatedAt

string<date-time>

required

agentId

string<uuid> | null

Identificador del agente asociado cuando aplica.

description

string | null

Maximum string length: 500

method

enum<string>

default:POST

Método HTTP para entregar eventos del webhook

Available options:

GET,

POST

secretPreview

string | null

Vista previa enmascarada del secreto (prefix...suffix).

lastDeliveryAt

string<date-time> | null

headers

object

Headers permitidos (allowlist). Nunca incluir Authorization.

Show child attributes

successCount

integer<int32>

Required range: x >= 0

failureCount

integer<int32>

Required range: x >= 0

Documentación

API Reference

MCP

Conocimiento

Blueprint

Plantillas

Misceláneos

Notificaciones

Crear un webhook

Suscribirse a eventos

Notificaciones que enviaremos

call.status.updated — registrada

call.status.updated — en curso

call.status.updated — finalizada

call.status.updated — error

Validación de firmas (opcional)

Reintentos y respuestas

Buenas prácticas

Authorizations

Headers

Body

Response

​Crear un webhook

​Suscribirse a eventos

​Notificaciones que enviaremos

​call.status.updated — registrada

​call.status.updated — en curso

​call.status.updated — finalizada

​call.status.updated — error

​Validación de firmas (opcional)

​Reintentos y respuestas

​Buenas prácticas

Authorizations

Headers

Body

Response

Crear un webhook

Suscribirse a eventos

Notificaciones que enviaremos

call.status.updated — registrada

call.status.updated — en curso

call.status.updated — finalizada

call.status.updated — error

Validación de firmas (opcional)

Reintentos y respuestas

Buenas prácticas