O que é

Um jeito da sua própria URL ser avisada, em tempo quase real, quando algo acontece numa OS — sem precisar ficar perguntando ao AtmusOS de tempos em tempos. Cada webhook cadastrado assina um ou mais eventos e recebe um POST assinado toda vez que um deles acontece.

Para que serve

Complementa as chaves de API: a chave de API é para perguntar (“como está a OS 42 agora?”); o webhook é para ser avisado (“me chame quando a OS 42 mudar de status”). Serve para disparar uma automação, atualizar um painel externo ou sincronizar outro sistema sem esperar por uma consulta.

Onde encontrar

Configurações → Webhooks, ou /webhooks. Ver a listagem exige só acesso à assistência; cadastrar, alterar, girar/revelar segredo ou revogar exige permissão de gerenciar configurações.

Eventos disponíveis

Evento Quando dispara
OS criada Uma OS nova é aberta no balcão
Status da OS alterado Qualquer mudança de status da OS (inclusive as que acontecem sozinhas, como quando um orçamento é aprovado)
Orçamento aprovado O cliente ou o atendente aprova um orçamento, total ou parcial
OS entregue O aparelho é entregue ao cliente

Como cadastrar um webhook

  1. Em Configurações → Webhooks, clique em Novo webhook.
  2. Informe a URL que vai receber os eventos — precisa estar pronta para aceitar um POST com corpo em JSON.
  3. Marque pelo menos um evento.
  4. Confirme. A tela mostra o segredo para verificar a assinatura das entregas.

Se o botão “Novo webhook” aparecer desabilitado com um aviso, é porque o servidor ainda não está configurado para a funcionalidade — fale com quem administra o AtmusOS da sua assistência.

Verificando a assinatura

Toda entrega chega com estes cabeçalhos:

X-AtmusOS-Event: service_order.status_changed
X-AtmusOS-Event-Id: 9c1e2f3a-...
X-AtmusOS-Timestamp: 1787721600
X-AtmusOS-Signature: sha256=3b1a...

A assinatura é um HMAC-SHA256 do texto "{timestamp}.{corpo bruto}", usando o segredo do webhook como chave. Calcule a mesma assinatura do seu lado e compare com o que veio no cabeçalho antes de confiar no conteúdo — sem isso, qualquer um que descubra a URL poderia forjar um evento.

Reenvio automático e manual

Uma entrega que falha (o seu servidor respondeu erro, ficou fora do ar ou demorou demais) é reenviada automaticamente algumas vezes, com um intervalo que cresce a cada tentativa. Esgotadas as tentativas, a entrega fica esgotada — visível em “Ver entregas” do webhook — e pode ser reenviada manualmente assim que o problema do outro lado for resolvido.

Segredo: girar e revelar

  • Revelar segredo: mostra o segredo atual de novo, a qualquer momento — diferente da chave de API, que só aparece uma vez.
  • Girar segredo: gera um segredo novo e descarta o anterior imediatamente. Use quando o segredo vazar ou como rotina de segurança; atualize a verificação do seu lado antes ou logo depois de girar, senão as próximas entregas vão parecer inválidas até você trocar.

Regras importantes

  • Um webhook só recebe os eventos que assinou.
  • A mesma notícia pode chegar mais de uma vez — use o eventId para identificar duplicata do seu lado.
  • Revogação é imediata e sem volta: nenhum evento novo é enviado a um webhook revogado.
  • Sem confirmação de recebimento de verdade (seu servidor não responder 2xx), o AtmusOS entende que falhou e tenta de novo.

Problemas comuns

Não chega nenhum evento Confira se o webhook está ativo (não revogado) e se assina o evento esperado. Veja o log em “Ver entregas” — se aparecer alguma tentativa com erro, o problema está na resposta do seu servidor.

As entregas chegam, mas a assinatura não bate O segredo usado na verificação provavelmente não é mais o atual — confira em “Revelar segredo” se ele foi girado depois da última vez que você copiou.

Uma entrega ficou esgotada O seu servidor não respondeu com sucesso depois de todas as tentativas automáticas. Corrija o que causou a falha (veja o erro em “Ver tentativas”) e use Reenviar.

Funcionalidades relacionadas