Skip to main content
Os webhooks são gerenciados pelas rotas /v2/webhooks da API de Clientes. Todas exigem o token de acesso da API no header Authorization, e a empresa é sempre a do token: não é possível consultar ou alterar webhooks de outra empresa.

Gere um token em /v2/autenticar

Envie email e password do usuário de integração para receber o accessToken.
As rotas de teste, logs e reenvio estão detalhadas em Testar e reenviar.

Envelope de resposta

As rotas seguem o mesmo envelope das demais rotas /v2: sucesso traz success: true e data; falha de negócio traz HTTP 400 com success: false e errors.
Nas rotas de leitura de um registro, um id inexistente ou de outra empresa responde 404. Nas rotas de escrita (alterar, excluir, testar, reenviar…), o mesmo caso responde 400 com a mensagem Endpoint não encontrado. — em nenhum dos casos a API revela que o id existe em outra empresa.

Cadastrar um webhook

POST /v2/webhooks
string
required
Nome para identificar o webhook. Máximo de 100 caracteres.
string
required
URL que receberá os eventos. Máximo de 2000 caracteres. Veja as regras da URL.
string[]
required
Códigos dos eventos assinados (ao menos um, sem repetição). Veja o catálogo de eventos.
Resposta (200):
O token tem o formato gwhtok_ seguido de 64 caracteres hexadecimais. O campo token completo só é devolvido nesta resposta e na rotação do token. Guarde-o em um cofre de segredos do seu sistema: nas consultas seguintes ele aparece apenas mascarado (tokenMascarado, com os 4 últimos caracteres).
É possível cadastrar mais de um webhook com a mesma URL; cada um terá o seu próprio token.

Regras da URL

  • Deve usar https.
  • Não pode conter usuário ou senha (https://usuario:senha@...).
  • Deve apontar para um endereço público na internet: localhost, 127.0.0.1, IPs de rede privada (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback, link-local e domínios terminados em .localhost, .local, .internal e .lan são recusados.
  • O host precisa ser resolvido por DNS no momento do cadastro.
  • A validação do endereço público é refeita a cada envio: se o host passar a resolver para um endereço privado, o envio falha definitivamente.
Para receber webhooks no seu ambiente local durante o desenvolvimento, use um túnel HTTPS público (por exemplo, um serviço de túnel ou de captura de webhooks).

Listar e consultar

GET /v2/webhooks devolve em data a lista de webhooks da empresa e GET /v2/webhooks/{idEndpoint} devolve um webhook, nos mesmos campos da resposta de cadastro, sem o campo token.
string (uuid)
Identificador do webhook.
string
Nome do webhook.
string
URL atual do webhook.
string[]
Códigos dos eventos assinados.
boolean
Se o webhook está recebendo eventos.
string
Token mascarado, com os 4 últimos caracteres.
integer
Tentativas de envio com falha seguidas. Volta a 0 após um sucesso.
string (date-time) | null
Preenchido quando o webhook foi desativado automaticamente por falhas.
string (date-time)
Data de cadastro.
string (date-time) | null
Data da última alteração.
Um idEndpoint inexistente ou de outra empresa responde 404 com { "success": false, "data": null }.

Alterar

PUT /v2/webhooks/{idEndpoint} recebe o mesmo corpo do cadastro (descricao, url e eventos) e aplica as mesmas validações. A resposta traz o webhook atualizado, sem o campo token.
A nova URL vale apenas para os logs criados depois da alteração. Logs anteriores, inclusive quando reenviados, continuam indo para a URL gravada no momento em que foram criados.

Ativar e desativar

PATCH /v2/webhooks/{idEndpoint}/situacao
  • Webhooks inativos não recebem novos eventos: nenhum log é criado para eles.
  • Logs que ainda estavam pendentes quando o webhook foi desativado são encerrados como Falha com o erro “Endpoint desativado”.
  • Ao reativar, o contador falhasConsecutivas volta a 0 e desativadoAutomaticamenteEm é limpo.
  • Um log não pode ser reenviado enquanto o webhook estiver inativo.

Desativação automática

Se o webhook acumular 20 tentativas de envio com falha seguidas, o Gestio o desativa automaticamente e preenche desativadoAutomaticamenteEm. Corrija o problema no seu sistema e reative o webhook pela rota acima. Um envio com sucesso zera o contador.
O contador é por tentativa, não por log: um único log que esgote as 6 tentativas soma 6 falhas consecutivas. Logs de teste não entram nessa conta.

Excluir

DELETE /v2/webhooks/{idEndpoint} Exclui definitivamente o webhook, os eventos assinados e todo o histórico de logs dele. Como o webhook deixou de existir, a resposta não o devolve: data é apenas true.
Depois da exclusão, o webhook some de GET /v2/webhooks e tanto ele quanto os logs dele respondem 404.
A exclusão é definitiva e apaga o histórico de logs junto. Para apenas parar de receber eventos preservando o histórico, use PATCH /v2/webhooks/{idEndpoint}/situacao com { "ativo": false }.
Se houver envios desse webhook ainda na fila no momento da exclusão, eles são simplesmente descartados, sem erro.

Rotacionar o token

POST /v2/webhooks/{idEndpoint}/rotacionar-token gera um novo token e o devolve uma única vez no campo token, no mesmo formato da resposta de cadastro. A partir da rotação, todos os logs novos e os reenvios usam o novo token, inclusive logs antigos que forem reenviados. Atualize o token no seu sistema logo após a rotação.
Para trocar o token sem perder eventos, aceite temporariamente o token antigo e o novo no seu receptor, rotacione e, depois de atualizar a configuração, deixe de aceitar o antigo.

Mensagens de erro