• Webhooks de usuário vs. webhooks de workspace
• Webhooks automatizados vs. webhooks manuais
• Etapas para configurar webhooks
• Verificação de solicitações de webhook
  • Como funciona
  • Etapas para verificar um webhook
  • Código de exemplo para verificação
• Esquema
  • Propriedades JSON
  • Payloads de "início da reunião"
  • Exemplo de payload
• Perguntas frequentes
  • Por que não recebo webhooks para algumas das minhas reuniões?
  • Os webhooks podem enviar relatórios gerados a partir de uploads de arquivos?
  • Posso obter acesso a todos os relatórios da minha equipe ou do meu workspace com webhooks?
  • Os webhooks fazem novas tentativas automaticamente quando ocorre uma falha?
  • Por que meu webhook não inclui uma assinatura?
  • Por que meu webhook aparece como "interrompido"?
• Artigos relacionados

Com os webhooks, o Read pode enviar notas de reunião e dados de relatórios para um endpoint personalizado, para que outras ferramentas ou serviços recebam atualizações de reuniões automaticamente. Quando um relatório fica disponível, o Read envia uma solicitação de webhook contendo os dados da reunião para o endpoint configurado.

Há dois tipos de webhooks:

• Webhooks de usuário enviam os relatórios de reunião de um único usuário (a pessoa que criou o webhook). Qualquer usuário pode configurá-los para suas próprias reuniões.
• Webhooks de workspace enviam os relatórios de reunião de todos os usuários do workspace para um único endpoint. Eles são criados e gerenciados por administradores e proprietários do workspace.

Se necessário, um usuário também pode acionar manualmente um webhook a partir de um relatório de reunião individual.

Pré-requisitos

• Os webhooks estão disponíveis somente nos planos Pro, Enterprise e Enterprise+.
• Os usuários devem verificar o endereço de e-mail antes de criar webhooks.
• Há um máximo de 20 webhooks por usuário e um limite separado de 20 webhooks de workspace; webhooks mais antigos devem ser excluídos para criar novos quando um limite for atingido.
• Somente administradores e proprietários do workspace podem criar ou editar webhooks de workspace.

Webhooks de usuário vs. webhooks de workspace

Os dois tipos de webhook compartilham o mesmo esquema de payload e o mesmo processo de verificação de assinatura. As principais diferenças são quem pode configurá-los e de quem são os relatórios enviados.

Os webhooks são acionados somente para relatórios aos quais um membro tinha acesso direto no momento em que o relatório foi criado. Eles não são acionados para relatórios que um membro vê somente por meio do Acesso a relatórios da equipe ou do Acesso global a relatórios (acesso indireto).

Webhooks automatizados vs. webhooks manuais

Webhooks automatizados são acionados quando o relatório da reunião é gerado com sucesso após o término de uma reunião. Você deve ter pelo menos acesso de "Visualizador" ao relatório no momento da reunião; portanto, eles não funcionam se o acesso tiver sido concedido depois da reunião. Em geral, eles são acionados apenas uma vez por relatório, exceto quando fazem novas tentativas automaticamente várias vezes, com espera exponencial, sempre que recebem um código de status HTTP diferente de 2xx do endpoint configurado. Após 25 tentativas, se ainda falhar, o webhook deixará de tentar e mudará para o status "Interrompido" (consulte "Motivos pelos quais meu webhook foi interrompido" abaixo).

Webhooks manuais são acionados por um usuário a partir da página de um relatório. Eles também funcionam se o acesso ao relatório tiver sido concedido depois da reunião, mas ele deve ser de pelo menos nível "Editor". Desde que você tenha pelo menos um webhook configurado, é possível clicar no botão de webhooks no menu de distribuição; uma janela pop-up será exibida, permitindo escolher para qual webhook você deseja enviar o relatório. Depois que ele for enviado com sucesso, uma mensagem de confirmação será exibida.

Etapas para configurar webhooks

1. Acesse a página de Integrações

Configurando um webhook de workspace? Os administradores e proprietários do workspace gerenciam esses webhooks na guia Workspace da página de Integrações. As etapas restantes (nome, URL, chave de assinatura, teste e ativação) são idênticas.

2. Na seção Webhooks, clique em "Criar webhook"

Se estiver criando um webhook de workspace, você também deverá reconhecer e confirmar que entende os riscos antes de continuar.

3. Insira um nome e uma URL para o webhook

Não use caracteres Unicode ou emojis UTF-8 no nome e forneça uma URL HTTPS. O aplicativo nesse URL deve estar configurado para receber um payload JSON com nosso esquema padrão.

Se estiver criando um webhook de workspace, você também terá a opção de acioná-lo quando uma reunião começar e deverá selecionar pelo menos uma das opções de acionamento.

4. (Opcional) Copie sua chave de assinatura

Como prática recomendada de segurança, geramos uma chave de assinatura exclusiva para cada webhook criado. Você pode usar essa chave posteriormente para verificar se as chamadas recebidas pelo seu endpoint personalizado realmente vêm do Read AI (mais detalhes abaixo).

5. (Opcional) Teste seu webhook

Recomendamos fazer um teste neste momento para identificar problemas antecipadamente. Você pode usar a opção "Enviar solicitação de teste" para acionar uma solicitação com dados fictícios ou, se quiser testar com dados reais de uma reunião, acessar um relatório antigo e acionar o webhook manualmente.

Se encontrar algum problema, verifique se o endpoint está ativo e configurado corretamente para retornar um código de status HTTP 2xx ao receber um payload JSON com nosso esquema padrão.

6. Faça uma reunião e observe o fluxo de dados

Observe que o status continuará aparecendo como "Pendente" até que você envie seu primeiro payload real de uma reunião. Desde que o URL fornecido responda com sucesso ao webhook quando ele for acionado, o status será atualizado para "Ativo".

Verificação de solicitações de webhook

Para ajudar a garantir que as solicitações de webhook recebidas sejam realmente enviadas pelo Read AI, cada entrega de webhook inclui uma assinatura criptográfica. Você pode usar a chave de assinatura fornecida na configuração do webhook para verificar se a solicitação se originou do Read AI e não foi modificada durante o trânsito. Esse recurso está disponível somente para novos webhooks criados após 17 de março de 2026.

Como funciona

Quando o Read AI envia um webhook, calculamos uma assinatura usando a chave de assinatura do webhook e o corpo bruto da solicitação. A assinatura resultante é incluída no cabeçalho da solicitação X-Read-Signature.

No seu servidor, você pode calcular independentemente a mesma assinatura usando a chave de assinatura. Se o valor calculado corresponder à assinatura incluída na solicitação de webhook, o payload será autêntico.

Etapas para verificar um webhook

1. Recupere a chave de assinatura do webhook
   Nas configurações de webhook do Read AI, você verá uma chave de assinatura associada ao seu endpoint de webhook. Armazene essa chave com segurança e use-a somente no seu servidor ao verificar solicitações de webhook.
2. Leia o corpo bruto da solicitação
   Capture o payload bruto exato enviado ao seu endpoint. Não o modifique, reformate ou analise antes da verificação, pois a assinatura é calculada usando o corpo bruto original.
3. Extraia o cabeçalho de assinatura
   Leia o valor do cabeçalho X-Read-Signature da solicitação recebida. Esse cabeçalho contém a assinatura HMAC gerada pelo Read AI.
4. Calcule sua própria assinatura
   Usando a chave de assinatura do webhook, calcule um hash HMAC SHA‑256 do corpo bruto da solicitação.
5. Compare as assinaturas
   Compare a assinatura calculada com o valor do cabeçalho X-Read-Signature. Se forem iguais, a solicitação foi enviada pelo Read AI e o payload não foi adulterado.

Observação: Os webhooks também contêm uma propriedade exclusiva request_id no corpo, que pode ser usada para detectar e ignorar payloads duplicados, evitando ataques de repetição.

Código de exemplo para verificação

Python

import base64
import hmac
import hashlib


# Replace with the body of the request
body = b'{...}'

# Replace with the value of the X-Read-Signature header received on each request
header_sig = "d2f733f07d3862f707e761be1b72c6533133977307abf272dabb66addfbec9a1"

# ⚠️ IMPORTANT: Store the signing key in a secure location, not in code. This is for illustrative purposes only.
signing_key = "GHx4YT/StkcArjYPypjFG48FbZvgzBuDBOz5pCecbro="

key_bytes = base64.b64decode(signing_key)
digest = hmac.new(key_bytes, body, hashlib.sha256).hexdigest()
if hmac.compare_digest(digest, header_sig.lower()):
    print("✅ Signature verified. This request came from Read AI!")
else:
    print("❌ Signature verification failed!")

JavaScript

const crypto = require('crypto');

// Replace with the body of the request
const body = '{...}';

// Replace with the value of the X-Read-Signature header received on each request
const headerSig = "d2f733f07d3862f707e761be1b72c6533133977307abf272dabb66addfbec9a1";

// ⚠️ IMPORTANT: Store the signing key in a secure location, not in code. This is for illustrative purposes only.
const signingKey = "GHx4YT/StkcArjYPypjFG48FbZvgzBuDBOz5pCecbro=";

const keyBytes = Buffer.from(signingKey, 'base64');
const digest = crypto.createHmac('sha256', keyBytes)
    .update(body, 'utf8')
    .digest('hex');

if (crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(headerSig.toLowerCase()))) {
    console.log("✅ Signature verified. This request came from Read AI!");
} else {
    console.log("❌ Signature verification failed!");
}

Go

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"encoding/hex"
	"fmt"
)

func main() {
	// Replace with the body of the request
	body := []byte("{...}")

	// Replace with the value of the X-Read-Signature header received on each request
	headerSig := "d2f733f07d3862f707e761be1b72c6533133977307abf272dabb66addfbec9a1"

	// ⚠️ IMPORTANT: Store the signing key in a secure location, not in code. This is for illustrative purposes only.
	signingKey := "GHx4YT/StkcArjYPypjFG48FbZvgzBuDBOz5pCecbro="

	keyBytes, err := base64.StdEncoding.DecodeString(signingKey)
	if err != nil {
		panic(err)
	}

	h := hmac.New(sha256.New, keyBytes)
	h.Write(body)
	digest := hex.EncodeToString(h.Sum(nil))

	if hmac.Equal([]byte(digest), []byte(headerSig)) {
		fmt.Println("✅ Signature verified. This request came from Read AI!")
	} else {
		fmt.Println("❌ Signature verification failed!")
	}
}

Ruby

require 'openssl'
require 'base64'

# Replace with the body of the request
body = '{...}'

# Replace with the value of the X-Read-Signature header received on each request
header_sig = "d2f733f07d3862f707e761be1b72c6533133977307abf272dabb66addfbec9a1"

# ⚠️ IMPORTANT: Store the signing key in a secure location, not in code. This is for illustrative purposes only.
signing_key = "GHx4YT/StkcArjYPypjFG48FbZvgzBuDBOz5pCecbro="

key_bytes = Base64.decode64(signing_key)
digest = OpenSSL::HMAC.hexdigest('SHA256', key_bytes, body)

if OpenSSL.secure_compare(digest, header_sig.downcase)
  puts "✅ Signature verified. This request came from Read AI!"
else
  puts "❌ Signature verification failed!"
end

Práticas recomendadas

• Sempre verifique as assinaturas de webhook antes de processar o payload.
• Rejeite solicitações com assinaturas X-Read-Signature ausentes ou inválidas.
• Armazene sua chave de assinatura com segurança e nunca a exponha em código do lado do cliente.
• Use uma função de comparação segura contra ataques de temporização ao comparar assinaturas.

Esquema

Propriedades JSON

Sempre que um webhook é acionado, o Read envia uma solicitação HTTP POST com um payload JSON bruto no corpo, contendo as seguintes propriedades de nível superior:

• session_id: Um identificador exclusivo da sessão da reunião
• trigger: O evento que acionou o webhook — meeting_end ou meeting_start (somente webhooks de workspace). Observe que acionar manualmente um webhook a partir de um relatório sempre envia meeting_end.
• title: O título da reunião
• start_time: O horário de início da reunião no formato UTC
• end_time: O horário de término da reunião no formato UTC
• participants: Uma matriz de participantes da reunião
• owner: O proprietário da reunião
• summary: O resumo geral da reunião
• action_items: Uma matriz de itens de ação discutidos durante a reunião
• key_questions: Uma matriz das principais perguntas levantadas durante a reunião
• topics: Uma matriz dos tópicos abordados na reunião
• report_url: Um URL para o relatório da reunião na interface web do Read
• chapter_summaries: Resumos mais detalhados da reunião, divididos em capítulos sequenciais, com os respectivos tópicos.
• transcript: A transcrição completa da reunião, incluindo nomes dos participantes e carimbos de data/hora no horário Unix (milissegundos).
• platform_meeting_id: O ID exclusivo dessa reunião em plataformas como Teams, Zoom ou Meet
• platform:  A plataforma em que a reunião foi gravada (observe que gravações feitas pelo aplicativo para computador ou dispositivo móvel do Read AI sempre listarão essa plataforma)
• request_id: ID exclusivo gerado para cada solicitação, que pode ser usado para ignorar payloads duplicados e evitar ataques de repetição.

Payloads de "início da reunião"

Webhooks de workspace também podem ser acionados no início de uma reunião. Como ainda não existe um relatório, um payload meeting_start contém somente o subconjunto a seguir do esquema padrão:

• session_id
• trigger ("meeting_start")
• title
• start_time
• owner
• platform
• platform_meeting_id
• request_id

Todos os outros campos (como end_time, summary, action_items, topics, chapter_summaries, transcript e report_url) não estão presentes no início da reunião. As entregas de meeting_start são assinadas com o mesmo cabeçalho X-Read-Signature; portanto, verifique-as exatamente como verificaria um payload meeting_end.

Exemplo de payload

Veja um exemplo de payload, que deve ser muito semelhante ao payload enviado em uma solicitação de teste de webhook.

{
  "session_id": "SESSIONID",
  "trigger": "meeting_end",
  "title": "Meeting Title",
  "start_time": "2026-01-01T00:00:00Z",
  "end_time": "2026-01-01T01:00:00Z",
  "participants": [
    {
      "name": "Participant One",
      "first_name": "Participant",
      "last_name": "One",
      "email": "participant_one@company.com"
    },
    {
      "name": "Participant Two",
      "first_name": "Participant",
      "last_name": "Two",
      "email": null
    }
  ],
  "owner": {
    "name": "Participant One",
    "first_name": "Participant",
    "last_name": "One",
    "email": "participant_one@company.com"
  },
  "summary": "Meeting summary goes here...",
  "action_items": [
    {
      "text": "Action item one"
    },
    {
      "text": "Action item two"
    }
  ],
  "key_questions": [
    {
      "text": "Key question one?"
    },
    {
      "text": "Key question two?"
    }
  ],
  "topics": [
    {
      "text": "Topic one"
    },
    {
      "text": "Topic two"
    }
  ],
  "report_url": "https://app.read.ai/analytics/meetings/SESSIONID",
  "chapter_summaries": [
    {
      "title": "Chapter one",
      "description": "First chapter description",
      "topics": [
        {
          "text": "Topic one"
        }
      ]
    },
    {
      "title": "Chapter two",
      "description": "Second chapter description",
      "topics": [
        {
          "text": "Topic two"
        }
      ]
    }
  ],
  "transcript": {
    "speaker_blocks": [
      {
        "start_time": "1719514000000",
        "end_time": "1719514001000",
        "speaker": {
          "name": "Speaker 1"
        },
        "words": "Good morning everyone!"
      },
      {
        "start_time": "1719514002000",
        "end_time": "1719514003000",
        "speaker": {
          "name": "Speaker 2"
        },
        "words": "Hi!"
      }
    ],
    "speakers": [
      {
        "name": "Speaker 1"
      },
      {
        "name": "Speaker 2"
      }
    ]
  }
  "platform_meeting_id": "abc-defg-hij",
  "platform": "meet",
  "request_id": "01KKVQZ19X57NMNFTS8YXJNZE4"
}