Webhooks - API HelpyGo

O que são Webhooks

Webhooks são notificações HTTP enviadas via método POST para uma URL registrada por você. Quando um evento relevante ocorre na sua conta, a API HelpyGo envia automaticamente uma requisição POST com os dados do evento para a URL configurada.

Como Registrar

Para registrar uma URL de webhook, faça uma requisição POST para o endpoint de cadastro:

POST https://www.helpygo.com.br/api/v1/webhook/novo

A URL registrada deve estar acessível publicamente via HTTPS e responder com status 200 para confirmar o recebimento.

Eventos Disponíveis

Ao registrar o webhook, você pode escolher quais eventos deseja receber:

Evento	Campo	Descrição
atendimento.criado	`atendimentoCriado`	Disparado quando um novo atendimento SAC é criado
atendimento.mensagem	`atendimentoMensagem`	Disparado quando um atendimento recebe uma nova mensagem (interação)
atendimento.encerrado	`atendimentoEncerrado`	Disparado quando um atendimento é encerrado
aplicativo.removido	`aplicativo`	Disparado quando o aplicativo é desinstalado da loja

Por padrão, todos os eventos estão habilitados. Para desabilitar um evento específico, envie o campo correspondente como false no cadastro do webhook.

Timeout e Retentativas

Configuração	Valor
Timeout máximo de resposta	`10 segundos`
Número máximo de retentativas	`5 tentativas`

Se a URL registrada não responder dentro de 10 segundos ou retornar um status diferente de 200, a API realizará até 5 tentativas adicionais com intervalo crescente entre elas.

Formato do Payload

Todas as notificações de webhook são enviadas em formato JSON contendo o tipo do evento e os dados associados:

Atendimento Criado

{
  "evento": "atendimento.criado",
  "data": {
    "idAtendimento": "abc123def456",
    "idLoja": 123,
    "canal": "WhatsApp",
    "tipo": "Mensagem Pós-Venda",
    "status": "aberto",
    "dadosCliente": {
      "nome": "João Silva",
      "telefone": "11999998888",
      "email": "joao@email.com"
    },
    "dataAbertura": "2025-07-14T10:30:00Z"
  }
}

Atendimento Mensagem

{
  "evento": "atendimento.mensagem",
  "data": {
    "idAtendimento": "abc123def456",
    "idLoja": 123,
    "canal": "WhatsApp",
    "direcao": "entrada",
    "remetente": "11999998888",
    "mensagem": "Olá, gostaria de saber sobre meu pedido",
    "dataHora": "2025-07-14T10:35:00Z"
  }
}

Atendimento Encerrado

{
  "evento": "atendimento.encerrado",
  "data": {
    "idAtendimento": "abc123def456",
    "idLoja": 123,
    "canal": "WhatsApp",
    "status": "encerrado",
    "dataEncerramento": "2025-07-14T15:00:00Z",
    "resumo": "Cliente solicitou informações sobre prazo de entrega. Resolvido."
  }
}

Estrutura do Payload

Campo	Tipo	Descrição
evento	string	Identificador do tipo de evento (ex: `atendimento.criado`, `atendimento.mensagem`, `atendimento.encerrado`)
data	object	Objeto contendo os dados específicos do evento

Modo Fila

Além do modo webhook (push), você pode optar pelo modo fila (pull). Neste modo, os eventos são armazenados numa fila e seu sistema consome via API:

GET https://www.helpygo.com.br/api/v1/fila/lista
DELETE https://www.helpygo.com.br/api/v1/fila/delete?codigo={idDocumento}

No modo fila, após processar o evento, remova-o da fila com o endpoint DELETE para evitar reprocessamento.