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 participant.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": "pending",
    "created": "2025-02-03T12:00:00Z",
    "started": null,
    "ended": null,
    "project": {
      "id": "456"
    }
  },
  "secret": "your-webhook-secret"
}

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"
    }
  },
  "secret": "your-webhook-secret"
}

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"
    }
  },
  "secret": "your-webhook-secret"
}

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",
    "project": {
      "id": "456"
    }
  },
  "participant": {
    "session": "session_abc123",
    "username": "João Silva",
    "ip": "192.168.1.100"
  },
  "timestamp": "2025-02-03T12:05:15Z",
  "secret": "your-webhook-secret"
}

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",
    "project": {
      "id": "456"
    }
  },
  "participant": {
    "session": "session_abc123",
    "username": "João Silva",
    "ip": "192.168.1.100"
  },
  "timestamp": "2025-02-03T12:28:45Z",
  "secret": "your-webhook-secret"
}

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",
    "project": {
      "id": "456"
    }
  },
  "participant": {
    "session": "session_abc123",
    "username": "João Silva",
    "ip": "192.168.1.100"
  },
  "timestamp": "2025-02-03T12:15:30Z",
  "secret": "your-webhook-secret"
}

7. Evento participant.disconnected

O evento participant.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": "participant.disconnected",
  "call": {
    "id": "123",
    "project": {
      "id": "456"
    }
  },
  "participant": {
    "session": "session_abc123",
    "username": "João Silva",
    "ip": "192.168.1.100"
  },
  "timestamp": "2025-02-03T12:15:28Z",
  "secret": "your-webhook-secret"
}

Descrição dos Campos

Campos comuns a todos os eventos: * event: Indica o tipo do evento * call.id: Identificador único da chamada * call.project.id: Identificador do projeto associado * secret: Segredo do webhook para validação

Campos específicos de eventos de chamada (call.*): * 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 * call.ended: Data e hora em que a chamada foi encerrada

Campos específicos de eventos de participante (participant.*): * participant.session: ID único da sessão WebRTC do participante * participant.username: Nome do participante * participant.ip: Endereço IP do participante * timestamp: Data e hora exata do evento

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.