Exportar datos de reuniones con webhooks
Usa la integración de webhooks para exportar datos de reuniones y crear integraciones personalizadas
Los webhooks de Circleback envían una solicitud POST con un cuerpo JSON a la URL HTTPS pública que elijas después de cada reunión que coincida. Cada solicitud se firma con un encabezado X-Signature que contiene un resumen HMAC-SHA256, para que puedas verificar que proviene de Circleback. Úsalos para exportar los datos de tus reuniones y crear integraciones personalizadas.
Configuración
- Abre Automatizaciones y selecciona Nueva automatización.
- Agrega condiciones a la automatización para limitar después de qué reuniones se ejecuta y selecciona Siguiente.
- Selecciona Enviar solicitud de webhook.
- Ingresa la URL del endpoint al que quieres enviar las solicitudes de webhook y los resultados de la reunión que quieres incluir.
- Si quieres, envía una solicitud de prueba con la reunión más reciente para verificar que funcione.
- Selecciona Listo.
- Ponle un nombre a tu automatización en la parte superior y selecciona Guardar.
Ahora, cada reunión que coincida con las condiciones de tu automatización se enviará a tu endpoint de webhook.
Puedes exportar tus reuniones anteriores seleccionando todas las reuniones y eligiendo tu nueva automatización en el menú Acciones.
Solicitudes
Una vez configurado, empezarás a recibir solicitudes POST en la URL del endpoint indicada con un cuerpo JSON que incluye los siguientes campos:
id(string): ID de la reunión en Circleback; se puede usar para generar un enlace a la reunión en Circleback (https://circleback.ai/meetings/${id})name(string): nombre de la reunióncreatedAt(string): fecha de creación de la reunión en formato de cadena ISOduration(number): duración de la reunión en segundosurl(string o null): URL de la reunión virtual (p. ej., Zoom, Google Meet, Microsoft Teams)recordingUrl(string o null): URL del archivo de grabación de la reunión, válida solo durante 24 horas (solo está disponible si guardar las grabaciones de reuniones está activado en la configuración)tags(array de strings): nombres de las etiquetas agregadas a la reuniónicalUid(string o null): identificador único del evento de calendario asociado a la reuniónattendees(array de objetos): asistentes de la reuniónname(string o null): nombre del invitado al evento de calendario si está asociado a un evento de calendario, o nombre del participante de la reuniónemail(string o null): correo electrónico del invitado al evento de calendario si está asociado a un evento de calendario
notes(string): notas de la reunión de Circleback con formato MarkdownactionItems(array de objetos): array de tareas creadas para la reuniónid(number): ID de la tarea en Circlebacktitle(string): título de la tareadescription(string): descripción de la tareaassignee(object o null): objeto del responsable de la tarea, o null si no está asignadaname(string o null): nombre del responsableemail(string o null): correo electrónico del responsable
status(string): estado de la tarea, 'PENDING' o 'DONE'
transcript(array de objetos): segmentos de la transcripción de la reuniónspeaker(string): nombre del hablantetext(string): palabras dichastimestamp(number): marca de tiempo en segundos que indica el inicio del segmento
insights(object):[insightName](clave de objeto string): nombre del insight creado por el usuario- array de objetos
insight(string, u object si el insight tiene campos personalizados): el resultado del insightspeaker(string o null): hablante al que está asociado el insight (si lo hay)timestamp(number o null): la marca de tiempo en segundos a la que está asociado el insight (si la hay)
- array de objetos
Ejemplo
{
"id": "WRweb12iCBimU6Vo8cD7z",
"name": "Event Venue Review",
"createdAt": "2023-07-25T20:30:57.926Z",
"duration": 1306.09,
"url": "https://meet.google.com/abc-defgh-xyz",
"recordingUrl": null,
"tags": ["Events"],
"icalUid": "1a2b3c@google.com",
"attendees": [
{ "name": "John Appleseed", "email": "john@example.com" },
{ "name": "Samantha Grey", "email": "sam@example.com" }
],
"notes": "#### Overview\n* Several options for event venues were reviewed...",
"actionItems": [
{
"id": 252,
"title": "Contact event venues",
"description": "Reach out to Sunriver Events and other potential event venues to see if they would be open to hosting the event this summer.",
"assignee": {
"name": "John Appleseed",
"email": "john@example.com"
},
"status": "PENDING"
},
{
"id": 253,
"title": "Review and finalize venue options",
"description": "Review pricing and availability of venues and pick a venue for the event.",
"assignee": null,
"status": "PENDING"
}
],
"transcript": [
{
"speaker": "John Appleseed",
"text": "Hey, how's it going?",
"timestamp": 4.56
},
{
"speaker": "Samantha Grey",
"text": "Going well, just testing webhooks in Circleback.",
"timestamp": 18.32
}
],
"insights": {
"Customer details": [
{
"insight": {
"Company name": "Initech",
"Number of employees": 120
},
"speaker": "John Appleseed",
"timestamp": 800
}
],
"Questions": [
{
"insight": "Is this thing on?",
"speaker": "Samantha Grey",
"timestamp": 49.15
},
{
"insight": "When will the webhook integration be ready?",
"speaker": "John Appleseed",
"timestamp": 120.12
}
]
}
}Verificar las solicitudes entrantes (opcional)
Para asegurarte de que los eventos de webhook recibidos provienen de Circleback, puedes verificar las solicitudes entrantes con un secreto de firma. Este paso es opcional, pero se recomienda para mayor seguridad.
Cuando configures el webhook en una automatización, recibirás un secreto de firma. Este secreto de firma es una cadena única y segura que se usa para generar una firma criptográfica para cada evento de webhook.
Para verificar la firma, puedes seguir estos pasos:
- Extrae la firma de los encabezados de la solicitud entrante. La firma está en un encabezado llamado
x-signature. - Genera la firma esperada con el secreto de firma y el cuerpo de la solicitud.
- Compara la firma esperada con la firma recibida. Si coinciden, la solicitud se considera válida y puedes procesar el evento de webhook.
Este es un ejemplo de implementación en TypeScript:
import { createHmac, timingSafeEqual } from 'crypto'
import express from 'express'
// Mount this on the webhook route so req.body stays the raw bytes.
// Do not use express.json() before verifying.
export const rawJsonBody = express.raw({ type: 'application/json' })
export const verifyWebhookSignature = (
requestBody: Buffer,
signature: string,
signingSecret: string
) => {
const expectedSignature = createHmac('sha256', signingSecret)
.update(requestBody)
.digest('hex')
const expected = Buffer.from(expectedSignature)
const provided = Buffer.from(signature)
return (
expected.length === provided.length &&
timingSafeEqual(expected, provided)
)
}
export const webhookEndpointHandler = async (
req: express.Request,
res: express.Response
) => {
try {
const requestBody = req.body
const signature = req.headers['x-signature']
const signingSecret = 'your-signing-secret'
if (
!Buffer.isBuffer(requestBody) ||
typeof signature !== 'string' ||
!verifyWebhookSignature(requestBody, signature, signingSecret)
) {
return res.status(401).json({ error: 'Invalid signature.' })
}
const payload = JSON.parse(requestBody.toString('utf8'))
await processWebhookEvent(payload)
return res.status(200).json({
message: 'Webhook event processed successfully.',
})
} catch (error) {
console.error('Error processing webhook event.', error)
return res.status(500).json({ error: 'Error processing webhook event.' })
}
}
app.post('/webhook', rawJsonBody, webhookEndpointHandler)Asegúrate de reemplazar 'your-signing-secret' con el secreto de firma real del paso de webhook de la automatización.
Al verificar la firma, puedes asegurarte de que los eventos de webhook que recibes provienen de Circleback y no fueron alterados. Esto ayuda a proteger tu aplicación contra accesos no autorizados y posibles ataques.
Reintentos
Si tu endpoint devuelve una respuesta que no es 2xx, genera un error o no responde en 5 minutos, Circleback reintenta la solicitud automáticamente, hasta 9 veces más. Debido a los reintentos, la misma reunión puede llegar más de una vez, así que usa el id de la reunión para omitir los duplicados.