V2

Webhooks

Configuração 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.

Integrações, API e webhooks: o catálogo de integrações, o assistente e os webhooks
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

ParaPermissão
Ver o painel, testar e ver as entregasConfig. webhooks, visualizar
Adicionar endpoint (novo webhook)Config. webhooks, criar
Editar, pausar, reenviarConfig. webhooks, atualizar
RemoverConfig. 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.

Painel Webhooks: endpoints com status, entregas recentes e assinatura
Painel Webhooks: endpoints com status, entregas recentes e assinatura

O que você vê, de cima para baixo

  1. 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.
  2. Ações de cada endpoint: Enviar evento de teste, Entregas, Editar, Remover e a chave de envio automático.
  3. 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.
  4. 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.

Passo 1 do assistente: destino, secret e envio automático
Passo 1 do assistente: destino, secret e envio automático
  1. 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 json de todo envio deste webhook, por exemplo {"origem": "sndesk"}.
    • Envio automático: desligado, os eventos ficam registrados como pendentes, para reenvio manual.
  2. 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.
  3. 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.
  4. Revisão e teste: o resumo de tudo e Enviar evento de teste, que faz um POST assinado com o evento teste sem gravar nada. Depois, Criar webhook.
Passo 2 do assistente: eventos que disparam o envio
Passo 2 do assistente: eventos que disparam o envio

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.

Entregas de um webhook: filtros, código HTTP e reenvio
Entregas de um webhook: filtros, código HTTP e reenvio
  • 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.

Relacionado