Webhooks
v2/configuracoes?pane=webhooks
8 min de leitura
Avise outro sistema (ERP, BI, portal do cliente, automação) em tempo real quando um chamado é criado, alterado, muda de status ou recebe interação. Cada envio é assinado e fica no histórico de entregas, com reenvio.
Transcrição do vídeo
Neste vídeo, você vai ver como o SNDesk conversa com outros sistemas: as integrações com ERPs e serviços, e os webhooks que avisam outros sistemas em tempo real.
Em Configurações, Integrações e dados, API e integrações, ficam as conexões em uso, com a saúde e a data da última sincronização, e o catálogo, com o logo de cada provedor: Bling, Omie, GestãoClick, Conta Azul, SuperLógica, Conexa, Google Agenda e Power BI. Uma integração pode ter mais de uma conexão, uma por conta ou filial.
Conectar abre o assistente: depois do provedor, as credenciais, com o link de redirecionamento para copiar no aplicativo do provedor, a descrição da conexão e as chaves. Em seguida vêm a autorização, com o teste, e a ativação, com a sincronização automática de clientes.
No Google Agenda, cada usuário conecta a própria conta Google: Conectar nova conta Google leva ao login do Google e, na volta, a conta aparece na lista, com a opção de compartilhar os eventos com os colegas. Quem só precisa da própria agenda pode ter só a permissão do Google Agenda, sem acesso aos ERPs.
Mais abaixo, os webhooks entre sistemas SNDesk encaminham chamados para outro SNDesk, e o link leva à documentação da API. O token da API do SNDesk ainda é gerado na interface V1.
No painel Webhooks ficam os endpoints que recebem os eventos do SNDesk em tempo real, com assinatura. Cada um mostra a situação, ativo, falhando, pausado ou nunca disparado, a URL, os eventos, o filtro e o código da última entrega, e a chave liga ou pausa o envio automático.
Adicionar endpoint abre o assistente: o destino, com a descrição, a URL e o secret, que você guarda para conferir a assinatura; depois os eventos, os filtros por cliente, técnico, chamado ou momento, e a revisão, com um evento de teste.
As entregas recentes mostram cada disparo, com o evento, o chamado e o resultado, e as que falharam têm Reenviar. Em Assinatura das requisições, o exemplo de validação mostra como o destino confere o cabeçalho de assinatura.
Os detalhes estão nos guias de Integrações e API e de Webhooks, na documentação do SNDesk. Até o próximo vídeo!
Antes de começar
| Para | Permissão |
|---|---|
| Ver o painel, testar e ver as entregas | Config. webhooks, visualizar |
| Adicionar endpoint (novo webhook) | Config. webhooks, criar |
| Editar, pausar, reenviar | Config. webhooks, atualizar |
| Remover | Config. webhooks, excluir |
Do outro lado, você precisa de um endereço HTTPS que aceite um POST com JSON. Quem cuida do sistema de destino deve guardar o secret para conferir a assinatura.
Onde fica
Configurações > Integrações & dados > Webhooks. Endereço: v2/configuracoes?pane=webhooks.

O que você vê, de cima para baixo
- Endpoints ("Cada endpoint recebe os eventos selecionados assim que ocorrem"), com Adicionar endpoint. Cada endpoint mostra o nome, a situação, a URL, os eventos, o filtro e o código HTTP da última entrega:
- Ativo: a última entrega foi aceita pelo destino.
- Falhando: o destino respondeu com erro (400 ou mais) ou não respondeu.
- Pausado: o envio automático está desligado.
- Nunca disparado: ainda não houve evento que casasse com o filtro.
- Ações de cada endpoint: Enviar evento de teste, Entregas, Editar, Remover e a chave de envio automático.
- Entregas recentes: os últimos cinco disparos de todos os endpoints, com o evento, o chamado, o resultado e quando foi. As que falharam ou ficaram pendentes têm Reenviar.
- Assinatura das requisições: como o destino confere o cabeçalho
X-Signature, com Ver exemplo de validação em PHP, Copiar payload de exemplo e o link para a Documentação da API (Swagger).
Criar um webhook
Adicionar endpoint abre o assistente Novo webhook, em quatro passos (o rodapé mostra "Passo 1 de 4", com Voltar e Continuar). Nada é enviado ao destino até você concluir o último.

- Destino:
- Descrição (obrigatória): o nome que aparece na lista, por exemplo "ERP da empresa — produção".
- URL de destino (obrigatória): sem
https://, o SNDesk completa. Não pode ser o próprio endereço do SNDesk, porque criaria um ciclo de eventos. - Secret: já vem gerado. Gerar cria outro, Copiar copia. Guarde agora: depois de salvar ele não aparece mais.
- Content-Type (
application/json) e Validar certificado do destino (ligue quando o destino tem certificado válido). - Avançado — JSON extra: um JSON fixo que vai no campo
jsonde todo envio deste webhook, por exemplo{"origem": "sndesk"}. - Envio automático: desligado, os eventos ficam registrados como pendentes, para reenvio manual.
- Eventos: marque um ou mais. O catálogo padrão tem Criação de chamados (
insert_chamado), Criação de Interação (insert_interacao), Alteração de status do chamado (setstatus) e Alteração de chamados (update_chamado); o tenant pode ter outros, como Criação de pré-chamado. Cada evento chega numa requisição separada. - Filtros (opcional): limite o que dispara por Cliente (busca a partir de 3 letras), Técnico, Chamado específico ou Momento (departamento, categoria ou subcategoria, com o Valor do momento). Sem filtro, vale para todos os chamados.
- Revisão e teste: o resumo de tudo e Enviar evento de teste, que faz um POST assinado com o evento
testesem gravar nada. Depois, Criar webhook.

Mensagens de validação que você pode ver: Dê um nome ao webhook, Informe a URL de destino, O domínio não pode ser o mesmo do SNDesk, O JSON extra precisa ser um JSON válido, Marque pelo menos um evento, Informe só o número do chamado, Escolha o valor do momento (ou limpe o filtro).
Editar, pausar e remover
- Editar abre o mesmo assistente com todos os passos liberados (clique no passo que quer ajustar). O secret aparece em branco: deixe assim para manter o atual.
- A chave da linha pausa ou retoma o envio automático. Pausado, os eventos continuam registrados como pendentes; nada se perde.
- Remover pede confirmação na própria linha. O endpoint e seus eventos saem; o histórico de entregas fica.
Entregas de um webhook
O ícone Entregas abre o histórico completo daquele endpoint.

- Busque por chamado ou referência, filtre por evento e pelos segmentos Todas, Sucesso, Falhas e Pendentes. Mostrar removidas inclui as que você tirou do histórico.
- Cada linha mostra evento, chamado, referência, código HTTP e quando. Payload e resposta mostra o que foi enviado e o que o destino respondeu.
- Reenviar dispara de novo; Remover do histórico esconde a linha (dá para ver com Mostrar removidas).
- Oito entregas por página.
Exemplos práticos
Situação: o ERP precisa saber de cada chamado aberto pela equipe de campo, para já reservar material. O que fazer: Adicionar endpoint > descrição "ERP — produção", URL do ERP, copie o secret para o ERP > evento Criação de chamados > filtro Momento Departamento, valor Manutenção em Campo > Enviar evento de teste > Criar webhook. Resultado: só os chamados desse departamento chegam ao ERP, cada um com a assinatura conferível.
Situação: o sistema do cliente ficou fora do ar por uma manhã e o endpoint aparece como Falhando. O que fazer: depois que o cliente confirmar que voltou, abra Entregas, segmento Falhas, e use Reenviar em cada entrega. Resultado: os eventos perdidos chegam; o endpoint volta a Ativo na próxima entrega aceita.
Situação: o BI de homologação vai ficar uma semana sem receber, mas não pode perder os eventos. O que fazer: desligue a chave do endpoint. Resultado: ele fica Pausado e as entregas ficam pendentes; quando quiser, reenvie pelo histórico.
Perguntas frequentes
Perdi o secret. Ele não é reexibido. Edite o webhook, clique em Gerar, copie o novo e atualize o sistema de destino antes de salvar.
O teste deu certo, mas o endpoint continua "Nunca disparado". O teste não conta como entrega. A situação muda no primeiro evento real que passar pelo filtro.
O que vai no corpo da requisição? Um JSON com event, idchamado, idref, json (o JSON extra) e dominio. Use Copiar payload de exemplo para ver o formato.
Limites e comportamentos que não são defeito
- A URL tem no máximo 255 caracteres e não pode apontar para o próprio domínio do SNDesk.
- Sem Validar certificado, o SNDesk envia mesmo para destino com certificado inválido ou autoassinado.
- Remover um webhook não apaga o histórico de entregas dele.