¶ Outros (Webhook)
O gateway Outros (Webhook) envia os eventos das Ordens de Serviço para um endereço seu, e não para uma plataforma conhecida. É a opção para quem quer receber as O.S. em um sistema próprio, num ERP que ainda não tem integração dedicada ou em uma automação interna.
A diferença em relação às demais integrações é a liberdade sobre a requisição: você define o endereço, o método HTTP, os cabeçalhos de autenticação e, se quiser, o formato do conteúdo de cada evento.
ℹ️ Este gateway não oferece o Agendamento pela Plataforma — ele apenas envia os eventos. O agendamento depende de uma agenda do outro lado, e por isso existe só nas integrações com plataformas conhecidas, como o iClass.
¶ Pré-requisitos
Antes de configurar, é necessário ter:
- Um endereço (URL) público capaz de receber requisições do HubSoft.
- A definição de como esse endereço se autentica — normalmente um cabeçalho com token.
- Permissão de acesso ao cadastro de Integrações para o usuário que vai configurar.
💡 O endereço precisa estar acessível pela internet. Endereços internos, que só existem na rede do provedor, não são alcançados pelo HubSoft.
¶ Configurando a integração
Acesse Configurações > Integrações > ERP e clique em Adicionar.
1. Preencha os dados da integração:
| Campo | Como preencher |
|---|---|
| Nome | Um nome para identificar a integração (ex.: Webhook interno) |
| Gateway | Selecione Outros (Webhook) |
| Envio de Eventos | Habilite para enviar as O.S. |
2. Informe os parâmetros:
| Parâmetro | Obrigatório | Para que serve |
|---|---|---|
url |
Sim | Endereço que recebe os eventos |
metodo |
Não | Método HTTP do envio: POST, PUT ou PATCH. Sem informar, usa POST |
header.<nome> |
Não | Cabeçalho HTTP adicional. Informe um parâmetro para cada cabeçalho |
Exemplo de cabeçalho de autenticação: o parâmetro header.Authorization com o valor Bearer abc123 faz o HubSoft enviar o cabeçalho Authorization: Bearer abc123 em toda requisição. O mesmo vale para qualquer outro cabeçalho que o seu endereço exija — basta trocar o nome depois do ponto.
3. Selecione os eventos que serão enviados, no grupo Ordem de Serviço — criar, atualizar, agendar, desagendar, fechar e remover. Para cada evento marcado, você ainda escolhe o formato do conteúdo (veja o tópico seguinte).
4. Salve a integração.
¶ Testando a comunicação
Neste gateway a ação Testar está disponível na listagem das integrações. Ela dispara uma requisição de teste para o endereço configurado, com um conteúdo simples de verificação, e informa o resultado.
O teste serve para confirmar que o endereço responde e que a autenticação está correta, antes de depender de uma O.S. real. Ele não gera registro de transmissão, porque não há evento de verdade envolvido.
✅ A requisição é considerada bem-sucedida quando o seu endereço responde com um código HTTP de sucesso (200 a 299). Qualquer outro código é tratado como recusa, e a mensagem mostra o código e a resposta recebida.
¶ Formato do conteúdo enviado
Para cada evento você escolhe entre padrão e personalizado.
¶ Conteúdo padrão
O formato padrão do HubSoft, igual para todos os eventos:
{
"evento": "ordem_servico.criar",
"tipo": "ordem_servico",
"data_evento": "2026-08-25 09:14:32",
"body": {
"id_ordem_servico": 1234,
"numero_ordem_servico": 5678
}
}
| Campo | O que traz |
|---|---|
evento |
Qual evento aconteceu |
tipo |
A entidade de origem |
data_evento |
Data e hora do envio |
body |
Os campos da Ordem de Serviço |
¶ Conteúdo personalizado
Quando o seu sistema espera um formato próprio, escolha personalizado e monte o JSON que ele recebe. Nos valores, use marcadores para trazer os dados da O.S.:
{
"numero": "[[payload.body.numero_ordem_servico]]",
"cliente": "[[payload.body.cliente_servico.cliente.nome_razaosocial]]",
"aberto_em": "[[payload.data_evento]]"
}
O marcador tem o formato [[payload.caminho]], onde o caminho segue a estrutura do conteúdo padrão — payload.body.<campo> para os campos da O.S. e payload.<campo> para os dados do envio. Também é possível alcançar dados relacionados, como os do cliente e do serviço, encadeando os nomes.
💡 O editor do conteúdo personalizado oferece sugestão automática dos campos disponíveis, o que evita erro de digitação no caminho.
⚠️ O conteúdo personalizado é montado por evento. Se cada evento do seu sistema espera um formato diferente, configure um a um.
¶ Como o envio funciona
O envio acontece automaticamente e em segundo plano, logo após o acontecimento na O.S. Quem está atendendo não precisa fazer nada, e uma indisponibilidade do seu endereço não interrompe a operação no HubSoft — o sistema tenta novamente.
Cada envio fica registrado com o conteúdo enviado, o código HTTP recebido, a resposta do seu endereço e o tempo que a requisição levou.
¶ Perguntas/Problemas Frequentes
Abaixo serão listadas algumas perguntas/problemas frequentes relacionados com o gateway Outros (Webhook). Caso alguma dessas situações aconteça e você tenha dificuldades para resolver, não hesite em chamar nosso suporte, pois estamos aqui para lhe ajudar.
¶ O teste falha com erro de autenticação. O que verificar?
Confirme o cabeçalho exigido pelo seu endereço e como ele foi informado nos parâmetros. O nome do cabeçalho é exatamente o que vem depois de header. — header.Authorization gera Authorization. Verifique também se o valor está completo, incluindo prefixos como Bearer.
¶ O teste passa, mas os eventos não chegam.
Verifique se a opção Envio de Eventos está habilitada e se os eventos desejados foram marcados no cadastro. O teste valida a comunicação com o endereço; o envio depende de a integração estar com os eventos selecionados.
¶ Meu endereço recebeu a requisição, mas o conteúdo não é o que eu esperava.
Confira o formato configurado naquele evento. Com o formato padrão, o conteúdo vem sempre na estrutura do HubSoft; para receber no formato do seu sistema, escolha personalizado e monte o JSON com os marcadores.
¶ Um marcador do conteúdo personalizado veio vazio.
O caminho informado não existe no conteúdo daquele evento. Use a sugestão automática do editor para conferir o nome do campo e o caminho até ele — inclusive nos dados relacionados, como os do cliente.
¶ Posso usar este gateway junto com uma integração de plataforma?
Sim. As integrações são independentes: dá para ter o iClass recebendo os eventos e, ao mesmo tempo, um webhook enviando as mesmas O.S. para um sistema seu. Cada integração tem os seus próprios parâmetros e a sua própria seleção de eventos.
¶ Como sei se um evento chegou ao meu sistema?
Todo envio fica registrado no HubSoft com a resposta recebida. Se houver dúvida sobre um envio específico, acione o suporte HubSoft informando o número da O.S. e o horário aproximado.