Pular para o conteúdo principal

Webhook

A tela de Webhook mostra o histórico de envios de webhook da empresa: cada vez que o idworks tenta notificar um sistema externo (ERP, e-commerce próprio, BI, etc.) sobre um evento — criação de SKU, emissão de NF, alteração de status de pedido, atualização de tracking — uma linha aparece aqui com data, tópico, endpoint, status (Sucesso ou Erro) e número de tentativas. A tela é somente leitura: ela serve para auditar, depurar e acompanhar a saúde da integração.

A configuração propriamente dita — endpoint que recebe os POSTs, cabeçalho de autenticação, quais eventos disparam webhook — fica em Configurações → Integrações → Minhas Integrações, na integração Webhook, ícone de engrenagem (Configuração). É lá que você liga e desliga cada tópico (Criação SKU, Status do pedido, Tracking entregue, etc.) e informa a URL do seu sistema.

Quando você expande uma linha do log, o idworks mostra lado a lado o conteúdo que foi enviado e a resposta recebida do seu sistema — útil para entender por que algo deu errado ou para validar o formato do que está chegando do outro lado.

Conceitos gerais (multi-conta, privilégios, parametrizações e padrões de tela) estão em Conceitos → Funcionamento do sistema.

Índice​

Conceito

Cadastro e edição

Busca e visualização

Regras de negócio

Referência rápida

O que é a tela Webhook?​

É uma tela de auditoria dos envios de webhook que o idworks faz para sistemas externos. Cada linha representa uma mensagem que o idworks tentou entregar ao endpoint configurado pela empresa, com:

  • Data do envio.
  • Tópico — qual evento gerou a notificação (SkuPost para criação de SKU, OrderStatus para alteração de status do pedido, InvoiceIssue para emissão de NF, etc.).
  • Endpoint — a URL para onde o POST foi feito.
  • Tentativas — quantas vezes o idworks já tentou entregar essa mensagem.
  • ID Webhook Log — identificador interno do registro, útil para suporte e correlação com logs do seu lado.
  • Status — Sucesso quando o seu sistema respondeu com sucesso (HTTP 2xx); Erro caso contrário.
  • Conta — empresa dona da notificação (em ambientes multi-conta).

📍 Onde: menu lateral → Configurações → Webhook.

Esta tela não cria nem altera webhooks — para isso, use a integração Webhook em Configurações → Integrações (ver pergunta correspondente).

Como o webhook funciona no idworks?​

O webhook é um POST HTTP que o idworks faz para uma URL do seu sistema cada vez que um evento habilitado ocorre. O fluxo interno:

  1. Uma ação no idworks (ex.: criação de SKU) acontece.
  2. O sistema enfileira uma mensagem com o evento e os dados do recurso afetado (id, URL relativa, conta, data).
  3. Um processo de fila lê a mensagem, consulta as configurações da empresa:
    • Endpoint (URL) cadastrado.
    • Cabeçalho de autenticação (chave e valor) cadastrados.
    • Se o tópico correspondente ao evento está ligado para a empresa.
  4. Se tudo estiver configurado e o tópico ligado, faz um POST no endpoint com timeout de 10 segundos, enviando os dados em JSON.
  5. Grava o resultado nesta tela: Sucesso se o destino respondeu com sucesso (HTTP 2xx) dentro do timeout; Erro caso contrário.
  6. Se o endpoint recusar de forma definitiva (por exemplo 400, 401, 404 ou 422), o envio fica como Erro e não é repetido. Se a falha for passageira (5xx, timeout, 408, 425, 429 ou queda de rede), a mensagem volta para a fila e é retentada automaticamente poucas vezes, com espera crescente — o campo Tentativas soma cada nova retentativa no mesmo registro.

O idworks não altera o ritmo dos envios para acompanhar o seu sistema: se o seu endpoint demorar, o timeout de 10s fecha a tentativa como erro e a fila reagenda.

Quais ações do idworks podem disparar um webhook?​

A integração Webhook tem um tópico por tipo de evento. Cada tópico é ligado ou desligado independentemente nos parâmetros da integração Webhook, em Configurações → Integrações. Os tópicos disponíveis estão agrupados por área:

ÁreaEventos disponíveis
ProdutoCriação, edição e exclusão de SKU; criação, edição e exclusão de preço; criação/edição/exclusão de fornecedor do SKU; criação/exclusão de código de barras adicional; criação/exclusão de variação; criação/edição/exclusão de código de barras de embalagem.
AnúncioCriação, edição e exclusão de anúncio (Hub); criação, edição e exclusão de variação de anúncio.
PedidoAlteração de status do pedido.
TransporteTracking entregue, em andamento, em atenção, saiu para entrega, extraviado.
Fiscal ProdutoEmissão, cancelamento, inutilização e denegação de NF.
Logística (WMS)Criar e finalizar recebimento, transferência entre armazém/endereço, finalizar inventário, ajuste de estoque.

A lista completa, com o nome técnico exato de cada tópico (que aparece na coluna Tópico do log), está em Configurações → Integrações → Minhas Integrações, abrindo a engrenagem (Configuração) da integração Webhook e percorrendo cada submenu.

Onde configuro o endpoint, autenticação e os tópicos que o meu sistema recebe?​

A configuração não é feita nesta tela. Para ligar a integração Webhook:

  1. Acesse Configurações → Integrações, aba Integrações Disponíveis, e ative Webhook (botão +), se a integração ainda não existir.
  2. Em Minhas Integrações, clique na engrenagem (Configuração) da integração Webhook e, no submenu Credenciais de Acesso, preencha:
    • Endpoint / URL — a URL HTTPS do seu sistema que vai receber os POSTs.
    • Chave header autorização — o nome do cabeçalho HTTP em que sua chave de API será enviada (ex.: Authorization).
    • Autenticação — o valor que vai dentro desse cabeçalho (ex.: Bearer abc123...).
  3. Salve.
  4. Nos submenus Produto, Anúncio, Pedido, Transporte, Fiscal Produto e Logística (WMS) da mesma janela de parâmetros, ligue cada evento (tópico) que você quer receber.

Sem o Endpoint preenchido, o idworks ignora todos os envios — não há retentativa contra um endpoint vazio. Sem o tópico ligado, o evento correspondente também é ignorado, mesmo que o endpoint esteja certo.

Como funciona a autenticação no envio?​

Cada POST para o seu endpoint inclui um cabeçalho com o nome e o valor que você configurou:

  • Chave header autorização define o nome do cabeçalho HTTP (ex.: Authorization, X-API-Key).
  • Autenticação define o valor desse cabeçalho (ex.: Bearer abc123..., eyJhbGciOi...).

Se os dois campos estiverem preenchidos, o idworks envia o cabeçalho. Se algum deles estiver em branco, o POST é feito sem autenticação (apenas com Content-Type: application/json). O valor da autenticação fica armazenado de forma protegida no idworks — o campo aparece como password na janela de parâmetros da integração.

O idworks não rotaciona essa chave automaticamente. Se o seu sistema invalidar a chave, atualize o valor no submenu Credenciais de Acesso da integração Webhook (em Configurações → Integrações → Minhas Integrações, engrenagem Configuração) para que as próximas tentativas voltem a ser autorizadas.

Como filtrar os logs de webhook?​

Use o botão Filtros no topo da tela. Os filtros disponíveis são:

  • Conta — filtra pela empresa dona da notificação (visível apenas quando há mais de uma conta cadastrada).
  • Data log — restringe o histórico a uma faixa de datas, baseada na data do primeiro envio da mensagem.
  • Tópico — match exato pelo nome técnico do tópico (ex.: SkuPost, OrderStatus, InvoiceIssue). Útil para isolar problemas de um evento específico.
  • Status — Sucesso ou Erro. Útil para acompanhar a saúde da integração ou listar só o que deu errado.

A listagem mostra até 1000 itens por página, ordenados do envio mais recente para o mais antigo.

Como ver o conteúdo completo enviado e a resposta do destino?​

Clique na linha do log para expandi-la. Dois blocos JSON aparecem:

  • Resposta — o conteúdo retornado pelo seu sistema (ou a mensagem de erro, se o POST falhou).
  • Dados — o conteúdo JSON que o idworks enviou para o seu endpoint, incluindo o tópico (Topic), a conta (AccountName), o momento da modificação (ModificationTimestamp) e identificadores do recurso afetado (id do SKU, do pedido, etc.) acompanhados de uma URL relativa para consulta no idworks.

Os dois blocos vêm formatados como JSON. Quando o envio resulta em erro, a Resposta traz um JSON montado pelo idworks com code (código do erro, como ECONNABORTED no timeout), message (texto do erro), status (código HTTP devolvido pelo seu sistema, quando houve resposta), data (corpo que o seu sistema devolveu), reason (detalhe extra da falha, quando houver) e retry (true em falha passageira, que entra na retentativa automática; false em recusa definitiva).

O que significa cada status (Sucesso e Erro)?​

StatusSignificado
SucessoO seu endpoint respondeu ao POST com sucesso (HTTP 2xx) dentro do timeout de 10 segundos. O idworks não retenta mais essa mensagem.
ErroO seu endpoint não respondeu (timeout, conexão recusada, DNS) ou respondeu com status diferente de 2xx (4xx, 5xx). Se a falha for passageira (5xx exceto 501 e 505, timeout, 408, 425, 429 ou queda de rede), a mensagem volta para a fila e é retentada automaticamente poucas vezes (até 3 entregas no total); cada retentativa atualiza o mesmo registro do log e incrementa Tentativas. Se for uma recusa definitiva (por exemplo 400, 401, 404, 422, 501, domínio inexistente ou certificado inválido), o envio não é repetido.

O log mostra sempre o resultado da última tentativa: uma mensagem que falhou na primeira entrega e foi entregue na segunda aparece como Sucesso com Tentativas = 2.

O que é o campo Tentativas?​

Conta quantas vezes o idworks já tentou entregar a mesma mensagem. A primeira tentativa começa em 1. Cada falha passageira devolve a mensagem para a fila, e a próxima execução incrementa o número no mesmo registro.

Use o campo para identificar problemas:

  • Tentativas = 1 e Status = Sucesso → entrega normal, sem problema.
  • Tentativas > 1 e Status = Sucesso → houve falhas anteriores que foram resolvidas. Vale checar se o seu endpoint teve instabilidade.
  • Tentativas = 3 e Status = Erro → as entregas se esgotaram; o evento não será repetido. Com menos tentativas e Status = Erro, a mensagem ainda pode estar aguardando a próxima entrega (falha passageira) ou já ter saído da fila (recusa definitiva). Confira o Endpoint e o conteúdo de Resposta para entender a causa e, depois de corrigir, gere o evento de novo.

O que acontece quando o meu endpoint está fora do ar?​

A mensagem fica registrada como Erro e volta para a fila, mas o idworks tenta poucas vezes: até 3 entregas, em poucos minutos. Se o endpoint ficar fora por 10 minutos ou mais, com 20 falhas seguidas, os eventos seguintes deixam de ser postados e aparecem como Erro, com a resposta "evento não enviado: o endpoint falhou N vezes seguidas…". Uma vez por minuto um evento é enviado para testar o endpoint; quando um deles é entregue, os envios voltam ao normal. Os eventos que ficaram como Erro nesse período não são reenviados quando o endpoint volta.

Se o endpoint voltar enquanto a mensagem ainda tem entregas pendentes, a próxima retentativa marca a mensagem como Sucesso e o ciclo encerra. O campo Tentativas acumula todas as tentativas, então uma mensagem entregue após falhas aparece com Tentativas 2 ou 3 e Status Sucesso.

O idworks não tem painel de reprocessamento manual nessa tela. Se uma mensagem antiga estiver em erro e o seu sistema agora estiver pronto para receber, a forma de "reprocessar" é gerar o evento de novo no idworks (ex.: salvar de novo o SKU para refazer um SkuPost).

Resumo de parametrizações​

Toda a configuração do Webhook acontece em Configurações → Integrações → Minhas Integrações, na integração Webhook (engrenagem Configuração). Não há parametrização da empresa no grupo idworks que afete esta tela — as configurações aqui são exclusivamente da integração.

ParametrizaçãoSubmenuO que muda quando ativada
Endpoint / URLCredenciais de AcessoURL HTTPS do seu sistema que recebe os POSTs. Sem ela, nenhum webhook é enviado.
Chave header autorizaçãoCredenciais de AcessoNome do cabeçalho HTTP em que a autenticação será enviada (ex.: Authorization).
AutenticaçãoCredenciais de AcessoValor do cabeçalho de autenticação (ex.: Bearer ...).
Cada tópico (Criação sku, Edição sku, Status pedido, Tracking entregue, Emissão de NF, etc.)Produto · Anúncio · Pedido · Transporte · Fiscal Produto · Logística (WMS)Quando ligado, eventos daquele tipo passam a gerar webhook. Quando desligado, o evento é ignorado (não é enviado e não aparece nesta tela).

Cada submenu de tópicos lista as opções específicas com o nome amigável (ex.: "Criação sku", "Status pedido", "Tracking entregue"). O nome técnico que aparece na coluna Tópico desta tela é o mesmo identificador da parametrização (ex.: SkuPost, OrderStatus, TrackingDelivered).

Privilégios da tela​

Esta tela tem privilégios próprios que controlam o que cada usuário pode fazer. Configure os perfis de acesso em Configurações → Perfis de Acesso vinculando os privilégios abaixo aos grupos desejados. Quando o usuário não tem o privilégio, a ação correspondente fica desabilitada na tela.

PrivilégioLibera
Visualizar WebhookAcesso à tela e à listagem dos logs (incluindo a expansão da linha com conteúdo enviado e resposta recebida).

A tela não tem privilégios de criar/editar/excluir — o log é gerado automaticamente pelo idworks a cada envio. Para mudar a configuração do webhook, o usuário precisa do privilégio de editar parametrizações da empresa.

Última atualização em