Exportar dados de reuniões com webhooks
Use a integração de webhook para exportar dados de reuniões e criar integrações personalizadas
Os webhooks do Circleback enviam uma solicitação POST com um corpo JSON para a URL HTTPS pública que você escolher após cada reunião correspondente. Cada solicitação é assinada com um cabeçalho X-Signature que contém um digest HMAC-SHA256, para que você possa verificar que ela veio do Circleback. Use-os para exportar os dados das suas reuniões e criar integrações personalizadas.
Configuração
- Abra Automações e selecione Nova automação.
- Adicione condições de automação para limitar após quais reuniões a automação é executada e selecione Avançar.
- Selecione Enviar solicitação de webhook.
- Insira a URL do endpoint para o qual você quer enviar as solicitações de webhook e os resultados da reunião que você quer incluir.
- Opcionalmente, envie uma solicitação de teste para a reunião mais recente para verificar se está funcionando.
- Selecione Concluído.
- Dê um nome à sua automação na parte superior e selecione Salvar.
Agora, toda reunião que corresponder às condições da sua automação será enviada para o seu endpoint de webhook.
Você pode exportar suas reuniões anteriores selecionando todas as reuniões e escolhendo sua nova automação no menu Ações.
Solicitações
Depois de configurado, você começará a receber solicitações POST na URL do endpoint informada, com um corpo JSON que inclui os seguintes campos:
id(string): ID da reunião no Circleback, pode ser usado para gerar um link para a reunião no Circleback (https://circleback.ai/meetings/${id})name(string): nome da reuniãocreatedAt(string): data de criação da reunião no formato de string ISOduration(number): duração da reunião em segundosurl(string ou null): URL da reunião virtual (por exemplo, Zoom, Google Meet, Microsoft Teams)recordingUrl(string ou null): URL do arquivo de gravação da reunião, válida por apenas 24 horas (disponível apenas se salvar gravações de reuniões estiver ativado nas configurações)tags(array de strings): nomes das tags adicionadas à reuniãoicalUid(string ou null): identificador único do evento de calendário associado à reuniãoattendees(array de objetos): participantes da reuniãoname(string ou null): nome do convidado do evento de calendário, se associado a um evento de calendário, ou nome do participante da reuniãoemail(string ou null): e-mail do convidado do evento de calendário, se associado a um evento de calendário
notes(string): notas da reunião do Circleback com formatação MarkdownactionItems(array de objetos): array de itens de ação criados para a reuniãoid(number): ID do item de ação no Circlebacktitle(string): título do item de açãodescription(string): descrição do item de açãoassignee(objeto ou null): objeto do responsável pelo item de ação, ou null se não houver responsávelname(string ou null): nome do responsávelemail(string ou null): e-mail do responsável
status(string): status do item de ação, 'PENDING' ou 'DONE'
transcript(array de objetos): segmentos da transcrição da reuniãospeaker(string): nome do falantetext(string): palavras faladastimestamp(number): marca de tempo em segundos que indica o início do segmento
insights(objeto):[insightName](chave de objeto string): nome do insight criado pelo usuário- array de objetos
insight(string, ou objeto se o insight tiver campos personalizados): o resultado do insightspeaker(string ou null): falante ao qual o insight está associado (se houver)timestamp(number ou null): a marca de tempo em segundos à qual o insight está associado (se houver)
- array de objetos
Exemplo
{
"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 solicitações recebidas (opcional)
Para garantir que os eventos de webhook recebidos venham do Circleback, você pode verificar as solicitações recebidas usando um segredo de assinatura. Esta etapa é opcional, mas recomendada para maior segurança.
Ao configurar o webhook em uma automação, você receberá um segredo de assinatura. Esse segredo de assinatura é uma string única e segura usada para gerar uma assinatura criptográfica para cada evento de webhook.
Para verificar a assinatura, siga estas etapas:
- Extraia a assinatura dos cabeçalhos da solicitação recebida. A assinatura está em um cabeçalho chamado
x-signature. - Gere a assinatura esperada usando o segredo de assinatura e o corpo da solicitação.
- Compare a assinatura esperada com a assinatura fornecida. Se forem iguais, a solicitação é considerada válida e você pode prosseguir com o processamento do evento de webhook.
Veja um exemplo de implementação em 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)Substitua 'your-signing-secret' pelo segredo de assinatura real da etapa de webhook da automação.
Ao verificar a assinatura, você garante que os eventos de webhook recebidos vêm do Circleback e não foram adulterados. Isso ajuda a proteger seu aplicativo contra acesso não autorizado e possíveis ataques.
Novas tentativas
Se o seu endpoint retornar uma resposta diferente de 2xx, apresentar erro ou não responder em até 5 minutos, o Circleback tenta enviar a solicitação novamente de forma automática, até mais 9 vezes. Por causa das novas tentativas, a mesma reunião pode chegar mais de uma vez, então use o id da reunião para ignorar duplicatas.