Referência técnica do Webhook

Se você ainda não sabe o que é ou como cadastrar um webhook, veja primeiro o guia de Webhooks.

​

Visão geral

• Método: POST
• Content-Type: application/json
• Entrega: em tempo real — assim que o evento acontece no IPBox
• Tentativas: uma única tentativa por evento, com timeout de 5 segundos. Não há retry automático em caso de falha — seu endpoint precisa responder rápido e com um status 2xx para confirmar o recebimento.

​

Headers enviados

​

Formato do payload

{
  "estado": "string",
  "t": 1725650000,
  "evento": "agente.login",
  "usuario_id": 42
}

• estado: estado interno do agente no momento do evento (online, offline, paused, busy ou ringing)
• t: timestamp Unix (segundos) de quando o evento foi gerado
• evento: código do evento — é este campo que você usa para saber qual dos eventos marcados no cadastro está chegando
• usuario_id: ID do agente no IPBox

​

Catálogo de eventos

​

Exemplos de payload

{
  "estado": "paused",
  "t": 1725650000,
  "evento": "agente.login",
  "usuario_id": 42
}

{
  "estado": "offline",
  "t": 1725650500,
  "evento": "agente.logout",
  "usuario_id": 42
}

{
  "estado": "paused",
  "t": 1725650100,
  "pausa_id": 3,
  "udate": 1725650100,
  "durmax": 900,
  "evento": "agente.pause_in",
  "usuario_id": 42
}

{
  "estado": "online",
  "t": 1725650300,
  "evento": "agente.pause_out",
  "usuario_id": 42
}

{
  "estado": "busy",
  "t": 1725650200,
  "udate": 1725650200,
  "evento": "agente.busy",
  "usuario_id": 42
}

{
  "estado": "ringing",
  "t": 1725650250,
  "evento": "agente.ringing",
  "usuario_id": 42
}

{
  "estado": "online",
  "t": 1725650400,
  "evento": "agente.online",
  "usuario_id": 42
}

​

Validando a origem da chamada

​

Exemplo em PHP

<?php
$payload = file_get_contents('php://input');
$secretRecebido = $_SERVER['HTTP_X_WEBHOOK_SECRET'] ?? '';

if ($secretRecebido !== 'SEU_SECRET_AQUI') {
    http_response_code(401);
    exit;
}

$data = json_decode($payload, true);

// $data['evento'], $data['usuario_id'], $data['estado'], $data['t']
// ... seu processamento aqui ...

http_response_code(200);

​

Exemplo com curl (simulando o recebimento)

curl -X POST "https://seusistema.com/webhook-ipbox" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: SEU_SECRET_AQUI" \
  -d '{"estado":"paused","t":1725650000,"evento":"agente.login","usuario_id":42}'

​

Boas práticas

• Responda rápido (idealmente em menos de 1 segundo) e com status 2xx — como não há retry automático, uma resposta lenta ou com erro faz você perder aquela notificação.
• Se precisar processar algo demorado a partir do evento, responda 200 imediatamente e processe de forma assíncrona no seu lado.
• Trate o campo evento como a fonte da verdade sobre o que aconteceu — não dependa só do campo estado, já que o mesmo valor de estado pode aparecer em mais de um tipo de evento.