Como posso receber eventos de outros sistemas no meu Octadesk com endereços de webhook?

Quer integrar suas ferramentas externas e aprender a receber eventos de outros sistemas no seu ambiente Octadesk por webhook? Neste artigo, te mostramos como gerar URLs exclusivas de integração para conectar sua loja virtual, CRM, ERP ou gateway de pagamento e receber avisos automáticos de dados e ações na sua conta sem complicações! 

Este recurso já está disponível para mim?

Os endereços de webhook estão disponíveis, junto com a liberação do Fluxo de eventos, para todas as contas com acesso ao WOZ, a IA da Octadesk. Você os encontra em uma nova aba, Webhooks, na página de API.

O que é um endereço de webhook, na prática?

Pense no endereço de webhook como uma caixa de correio exclusiva do Octadesk. Você cria a caixa, entrega o endereço para o outro sistema e, a partir daí, toda vez que algo acontecer lá, ele deixa um aviso nessa caixa. O Octadesk fica esperando os avisos chegarem, 24 horas por dia; ele não precisa ficar consultando o outro sistema para saber se há novidades.

Quem decide quando enviar o aviso é o sistema de origem. Por exemplo: na sua loja virtual, você escolhe que o aviso seja enviado quando um carrinho for abandonado; no seu ERP, quando um pedido mudar de status.

Como gero um endereço de webhook?

1. Acesse Configurações, depois Geral, clique em API e abra a aba Webhooks.

2. Clique em Gerar endereço webhook.

3. Dê um nome ao endereço (até 30 caracteres). Use algo que identifique a origem e o evento, como "Yampi - carrinho abandonado" ou "ERP - pedido enviado".

4. Clique em Gerar e ativar. O endereço aparece na lista já ativo.

5. Para copiar a URL, clique nos três pontinhos do endereço e escolha Copiar endereço webhook. Você também pode abrir Ver detalhes para ver a URL completa e um exemplo de chamada.

A lista mostra, para cada endereço: nome, quem criou, a URL, a data de criação, a última execução e o status (ativo ou inativo).

Quem configura o endereço no outro sistema?

A integração é feita a quatro mãos. O Octadesk gera o endereço; o cadastro desse endereço no sistema de origem é feito por você ou por alguém do seu time que tenha acesso a esse sistema.

Por segurança e em respeito à Lei Geral de Proteção de Dados (LGPD), a equipe Octadesk não acessa o painel de sistemas de terceiros nem visualiza os dados que estão lá. Nosso time pode orientar sobre o lado do Octadesk, mas a configuração do outro sistema precisa de alguém da sua empresa. Se você não tem acesso ao sistema de origem, acione o responsável por ele ou o seu time de TI.

Como o outro sistema deve chamar o endereço?

O sistema de origem faz uma requisição POST para a URL do endereço, com o conteúdo em JSON. A tela Ver detalhes traz um exemplo de chamada pronto para copiar.

POST https://<endereço gerado pelo Octadesk>/execute

Content-Type: application/json

{

  "event": "pedido.enviado",

  "payload": {

    "pedido_id": "78432",

    "cliente_nome": "João da Silva",

    "telefone": "11987654321",

    "rastreio": "BR123456789"

  }

}

Alguns pontos sobre o conteúdo enviado:

• Qualquer JSON válido é aceito. Você não precisa seguir uma estrutura fixa. Sistemas como Yampi, RD Station, Shopify ou gateways de pagamento enviam o formato deles, e o Octadesk registra como veio.

• Recomendamos o formato com event e payload quando você controla a origem (por exemplo, um sistema interno da sua empresa). O campo event nomeia o que aconteceu e ajuda a identificar cada disparo no histórico. Ele também permite que um único endereço receba vários tipos de evento, com o bot decidindo o que fazer com cada um por meio das Saídas condicionais do componente Formate informações com a IA.

• O conteúdo precisa ser JSON. Chamadas com outro tipo de conteúdo são registradas, mas os dados podem não ficar disponíveis para o fluxo.

O Octadesk responde rapidamente com um código de sucesso assim que recebe a chamada e processa o fluxo em seguida. Isso evita que sistemas com limite de tempo de resposta (a Yampi, por exemplo, exige resposta em até 5 segundos) marquem o envio como falha.

Como consulto o histórico de disparos e o payload?

Na tela Ver detalhes de um endereço, o Histórico de disparos lista cada chamada recebida com data e hora, o status do recebimento e a ação Ver payload, que abre exatamente o conteúdo que chegou.

O histórico é o primeiro lugar para olhar quando algo não acontece como esperado:

• A chamada não aparece no histórico: ela não chegou ao Octadesk. Confira a URL copiada, se o endereço está ativo e se o sistema de origem realmente disparou.

• A chamada aparece com sucesso, mas o fluxo não fez o que devia: o recebimento está certo; o problema está no fluxo ou no bot. Veja a seção de diagnóstico do artigo Como acionar um Fluxo de eventos a partir de um webhook de outro sistema?.

• O payload está vazio ou diferente do esperado: confira o formato que o sistema de origem está enviando. O que aparece em Ver payload é exatamente o que chegou.

Como ativo, inativo ou troco um endereço?

• Inativar interrompe o recebimento na hora. Chamadas para um endereço inativo não executam nenhum fluxo. O histórico anterior é mantido.

• Ativar volta a receber.

• Para trocar a URL, gere um novo endereço, atualize a configuração no sistema de origem e inative o antigo. Não é possível editar a URL de um endereço existente.

Existe limite de endereços ou de avisos recebidos?

Não há um limite de quantidade de endereços divulgado. O volume de avisos recebidos segue os mesmos limites de uso das demais APIs do Octadesk.

Como mantenho meu endereço de webhook seguro?

Qualquer sistema que conheça a URL de um endereço ativo consegue disparar o fluxo ligado a ele. Por isso, trate a URL como uma senha:

• Não a publique em repositórios, documentação aberta, prints ou gravações.

• Compartilhe apenas com quem vai configurar o sistema de origem.

• Se suspeitar de vazamento, gere um novo endereço e inative o antigo.

• Antes de ligar um endereço a um fluxo que envia mensagens ou altera dados, considere quem tem acesso à URL.

O que significam os termos que aparecem neste artigo?

1. Webhook: um aviso automático que um sistema envia para outro quando algo acontece. É como uma notificação no celular, só que entre sistemas.

2. Endereço de webhook (URL): o "endereço de entrega" desse aviso. No Octadesk, é gerado na aba Webhooks.

3. Payload: o conteúdo do aviso, com os dados do acontecimento (nome, telefone, valor do pedido, etc.).

4. JSON: o formato de texto em pares de "nome e valor" usado no payload. Exemplo: "telefone": "11987654321".

5. POST: o tipo de chamada usado para enviar dados a um endereço. Funciona como "publicar" uma informação nesse endereço.

Quais são as boas práticas ao usar endereços de webhook?

• Um endereço por origem e por evento. Facilita identificar de onde veio cada aviso e inativar uma integração sem afetar as outras.

• Nome descritivo. "Loja - carrinho abandonado" diz mais que "webhook 1".

• Dispare um teste antes de montar o fluxo. Use o exemplo de chamada da tela de detalhes ou um evento de teste do próprio sistema de origem e confira o payload no histórico. Assim você conhece a estrutura dos dados antes de configurar o bot.

• Filtre na origem sempre que possível. Se o sistema de origem permite escolher quais eventos enviar (a Yampi, por exemplo, permite escolher eventos e produtos ao criar o webhook), envie só o que o fluxo vai usar.

• Cuide dos dados pessoais. O payload pode trazer nome, telefone, e-mail e até documento do cliente. Limite quem tem acesso à aba Webhooks e ao histórico.

Com o endereço criado e um disparo de teste no histórico, você já pode ligá-lo a um Fluxo de eventos. O passo a passo completo, com um caso real de recuperação de carrinho abandonado, está em Como acionar um Fluxo de eventos a partir de um webhook de outro sistema?. Seguindo esses cuidados, sua operação recebe informações de outros sistemas com agilidade, preservando a segurança e a integridade dos dados dos seus clientes.