Configuração de Webhooks

Configurando Webhooks

1. No painel, vá até Webhooks.
2. Clique em + Novo Webhook e insira o nome e a URL do seu servidor.
3. Escolha os eventos que deseja monitorar.

Info

Atualmente, suportamos os seguintes eventos para chamadas: call.created, call.started, call.ended, participant_joined, participant_left, participant_reconnected e disconnected.

Eventos Disponíveis

1. Evento call.created

O evento call.created é disparado sempre que uma nova chamada é criada no sistema. Esse evento é útil para iniciar processos automatizados, como notificações para usuários ou inicializações de integrações.

Exemplo de Payload

{
  "event": "call.created",
  "call": {
    "id": "123",
    "status": "created",
    "created": "2025-02-03T12:00:00Z",
    "started": null,
    "ended": null,
    "project": {
      "id": "456"
    }
  },
  "data": {},
  "timestamp": "2025-02-03T12:00:00Z"
}

2. Evento call.started

O evento call.started é disparado quando o primeiro participante entra na chamada. Útil para iniciar gravações, notificações ou qualquer lógica que deva ocorrer quando a chamada de fato inicia.

Exemplo de Payload

{
  "event": "call.started",
  "call": {
    "id": "123",
    "status": "active",
    "created": "2025-02-03T12:00:00Z",
    "started": "2025-02-03T12:05:00Z",
    "ended": null,
    "project": {
      "id": "456"
    }
  },
  "data": {},
  "timestamp": "2025-02-03T12:05:00Z"
}

3. Evento call.ended

O evento call.ended é disparado quando uma chamada é encerrada. Ele pode ser usado para registrar informações sobre a duração da chamada, finalizar processos ou gerar relatórios.

Exemplo de Payload

{
  "event": "call.ended",
  "call": {
    "id": "123",
    "status": "ended",
    "created": "2025-02-03T12:00:00Z",
    "started": "2025-02-03T12:05:00Z",
    "ended": "2025-02-03T12:30:00Z",
    "project": {
      "id": "456"
    }
  },
  "data": {},
  "timestamp": "2025-02-03T12:30:00Z"
}

4. Evento participant_joined

O evento participant_joined é disparado sempre que um participante entra na chamada. Útil para rastreamento de presença e notificações em tempo real.

Exemplo de Payload

{
  "event": "participant_joined",
  "call": {
    "id": "123",
    "status": "active",
    "created": "2025-02-03T12:00:00Z",
    "started": "2025-02-03T12:05:00Z",
    "ended": null,
    "project": {
      "id": "456"
    }
  },
  "data": {
    "session": "session_abc123",
    "username": "João Silva",
    "ip": "192.168.1.100"
  },
  "timestamp": "2025-02-03T12:05:15Z"
}

5. Evento participant_left

O evento participant_left é disparado quando um participante sai da chamada voluntariamente. Útil para atualizar listas de presença e calcular tempo de permanência.

Exemplo de Payload

{
  "event": "participant_left",
  "call": {
    "id": "123",
    "status": "active",
    "created": "2025-02-03T12:00:00Z",
    "started": "2025-02-03T12:05:00Z",
    "ended": null,
    "project": {
      "id": "456"
    }
  },
  "data": {
    "session": "session_abc123",
    "username": "João Silva",
    "ip": "192.168.1.100"
  },
  "timestamp": "2025-02-03T12:28:45Z"
}

6. Evento participant_reconnected

O evento participant_reconnected é disparado quando um participante reconecta após uma queda de conexão. Útil para monitoramento de qualidade de rede.

Exemplo de Payload

{
  "event": "participant_reconnected",
  "call": {
    "id": "123",
    "status": "active",
    "created": "2025-02-03T12:00:00Z",
    "started": "2025-02-03T12:05:00Z",
    "ended": null,
    "project": {
      "id": "456"
    }
  },
  "data": {
    "session": "session_abc123",
    "username": "João Silva",
    "ip": "192.168.1.100"
  },
  "timestamp": "2025-02-03T12:15:30Z"
}

7. Evento disconnected

O evento disconnected é disparado quando um participante perde a conexão inesperadamente. Útil para identificar problemas de rede e qualidade de serviço.

Exemplo de Payload

{
  "event": "disconnected",
  "call": {
    "id": "123",
    "status": "active",
    "created": "2025-02-03T12:00:00Z",
    "started": "2025-02-03T12:05:00Z",
    "ended": null,
    "project": {
      "id": "456"
    }
  },
  "data": {
    "session": "session_abc123",
    "username": "João Silva",
    "ip": "192.168.1.100"
  },
  "timestamp": "2025-02-03T12:15:28Z"
}

Descrição dos Campos

Campos comuns a todos os eventos:

• event: Indica o tipo do evento
• call.id: Identificador único da chamada
• call.status: Estado atual da chamada (created, active, ended)
• call.created: Data e hora em que a chamada foi criada
• call.started: Data e hora em que a chamada foi iniciada (null se ainda não iniciou)
• call.ended: Data e hora em que a chamada foi encerrada (null se ainda não encerrou)
• call.project.id: Identificador do projeto associado
• data: Dados adicionais específicos do evento
• timestamp: Data e hora exata do evento

Campos específicos de eventos de participante (participant_* e disconnected):

• data.session: ID único da sessão WebRTC do participante
• data.username: Nome do participante
• data.ip: Endereço IP do participante

Danger

Configure a URL do webhook na plataforma, associando-a ao seu projeto.\ Crie um endpoint HTTP seguro para receber as requisições do webhook.

Segurança e Controle

Implementar boas práticas de segurança é crucial para garantir que sua aplicação lide adequadamente com eventos externos. Aqui estão algumas considerações importantes:

• Verificação de IPs: Considere implementar listas de permissões para garantir que apenas IPs confiáveis possam enviar eventos para seu sistema.
• Proteção contra Ataques: Esteja atento a possíveis ataques, como ataques de repetição, e implemente medidas como timestamps ou nonces para se proteger contra eles.