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 → Parametrizações, na integração Webhook. É 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.

Í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.
  • 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 Configurações → Parametrizações → Webhook (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. Em caso de erro, a mensagem volta para a fila e é retentada automaticamente — 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 em Configurações → Parametrizações → Webhook. Os tópicos disponíveis estão agrupados por área:

ÁreaEventos disponíveis
ProdutoCriação, edição e exclusão de SKU; criação/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)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 → Parametrizações, abrindo a 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 → Parametrizações → Webhook (submenu Credenciais de Acesso).
  2. 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) do mesmo grupo Webhook, 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 tela de Parametrizações.

O idworks não rotaciona essa chave automaticamente. Se o seu sistema invalidar a chave, atualize o valor em Configurações → Parametrizações → Webhook → Credenciais de Acesso 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 geralmente traz a mensagem técnica do seu sistema (ex.: "401 Unauthorized", "timeout").

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). A mensagem volta para a fila e será retentada automaticamente. Cada retentativa atualiza o mesmo registro do log e incrementa Tentativas.

O log mostra sempre o resultado da última tentativa: uma mensagem que falhou nas três primeiras e foi entregue na quarta aparece como Sucesso com Tentativas = 4.

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 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 alto e Status = Erro → a mensagem ainda está sendo retentada (ou já atingiu o limite da fila). Confira o Endpoint e o conteúdo de Resposta para entender a causa.

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

A mensagem fica registrada como Erro e volta para a fila. As retentativas continuam enquanto o seu endpoint não responder com sucesso — o idworks não tem uma "lista negra" automática: enquanto a mensagem estiver na fila, será retentada periodicamente.

Quando o endpoint voltar, 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 várias falhas aparece com Tentativas alto 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 → Parametrizações, na integração Webhook. 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 idworks ignora o evento (não enfileira, não envia, não loga).

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 Key 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.