Um webhook é um endereço do seu ERP ou de um parceiro que a Kamino chama quando um evento acontece, como um pagamento confirmado ou um recebimento registrado. Com ele, o outro sistema fica sabendo na hora, sem precisar perguntar.
Onde ficam os webhooks e quem pode mexer neles
Em Configurações › Integrações › Webhooks, na plataforma web. A lista pede a permissão de ver webhooks; cada ação (cadastrar, pausar, rotacionar, reenviar) tem permissão própria.
Quem não tem a permissão vê o aviso Você não administra o acesso desta conta. Criar, pausar e excluir webhook é de quem administra o acesso à plataforma.
O que a lista de webhooks mostra
Acima da lista de webhooks, uma linha resume a conta: quantos webhooks existem, quantos estão ativos diante do limite e quantos foram desativados pela plataforma. Quando há entregas retidas, o link entregas retidas abre o histórico já filtrado nelas.
A lista traz, por webhook, o nome e o endereço, o ambiente, os eventos assinados, a taxa de entregas aceitas e a última falha. A coluna Onde atua mostra os grupos e as empresas de onde ele recebe eventos. A situação aparece num selo abaixo do nome: Pausado, Desativado por falhas ou Falhando, quando menos da metade das entregas recentes foi aceita.
O histórico de entregas dos webhooks
O Histórico de entregas mostra cada evento que saiu (ou tentou sair), para qual webhook, a situação e o que o endereço respondeu. Ele abre pelo botão Entregas, no alto da tela de webhooks, ou por Ver entregas, no painel de um webhook, já recortado nele. Ele abre dentro de Configurações, com Webhooks marcado no menu, e tem endereço próprio.
Cada entrega tem uma destas situações:
Entregue — o endereço respondeu aceitando o envio.
Tentando — falhou e será enviada de novo sozinha, com espera crescente entre as tentativas.
Esgotada — acabaram as tentativas automáticas. Ela só sai por reenvio manual.
Retida — o webhook foi desligado, e a entrega foi cancelada sem chegar a sair.
O que dá para fazer na tela de webhooks
Cadastrar um webhook. Em Novo webhook: nome, endereço, quais eventos (todos, por domínio ou um a um) e, se quiser, um e-mail para avisos. O endereço precisa ser HTTPS e público. Em Começar a enviar, escolha Assim que criar ou Depois que eu ativar; a segunda opção cria o webhook pausado.
Guardar o segredo. Logo depois de criar, a tela mostra o segredo que assina cada chamada. Ele aparece uma vez só: fechar o painel descarta o valor.
Enviar evento de teste, no painel do webhook, para conferir o endereço sem esperar um evento de verdade. A tela mostra o que o endereço respondeu e os cabeçalhos enviados. O teste não muda a situação do webhook.
Rotacionar o segredo. A rotação pede o motivo e a confirmação em duas etapas. Por padrão, o segredo antigo continua valendo por 7 dias, para o parceiro trocar sem parar de receber. Encerrar convivência agora corta o antigo antes do prazo.
Pausar e retomar um webhook, com Pausar envio e Retomar envio.
Religar um webhook que a plataforma desativou, com o botão Reativar.
Reenviar entregas, no histórico, uma a uma ou em lote (até 100 por vez).
Regras, prazos e limites dos webhooks
Até 10 webhooks ativos por conta. O limite é da Kamino e vale para o webhook novo, o retomado e o religado. No limite, o botão Novo webhook fica travado: pause ou exclua um antes de ativar outro.
Só endereço HTTPS, público e sem usuário e senha. A Kamino confere o endereço no cadastro e antes de cada envio. A autenticação é pela assinatura do envio, com o segredo do webhook.
O mesmo endereço não serve aos dois ambientes. Ao cadastrar, você escolhe o Ambiente: Teste ou Produção, e o mesmo endereço não pode estar nos dois.
O evento de teste vai para o endereço do próprio webhook. O botão Enviar evento de teste chama o endereço cadastrado, inclusive num webhook de Produção. Para testar sem chamar a produção do parceiro, use um webhook de Teste com outro endereço.
Até 8 tentativas por entrega. Uma entrega recusada é tentada até 8 vezes no total, em intervalos crescentes, por pouco mais de um dia.
Desativação automática. A Kamino desativa o endereço que responde 410, que falha 10 vezes seguidas ou que passa 7 dias falhando sem nenhum sucesso.
Convivência de 7 dias na rotação do segredo. Por padrão, o segredo antigo vale por 7 dias depois da rotação. Na rotação por Suspeita de vazamento, o antigo deixa de valer na hora.
Reenvio em lote de até 100 entregas. Acima disso, Reenviar as selecionadas fica travado. A tela avisa Acima do limite de um lote — reduza a seleção. Divida a seleção em lotes de até 100 e envie cada lote.
Histórico por 90 dias. O detalhe das entregas fica 90 dias. A resposta do parceiro só é guardada quando ele recusa o envio, e por 30 dias.
A ordem de chegada não é garantida. Cada envio traz o momento em que o evento aconteceu, e é por ele que o parceiro descarta o evento mais antigo.
O que confunde nos webhooks
Pausada e desativada pela plataforma não são a mesma coisa. Pausar é decisão sua. A Kamino desativa sozinha o endereço que parou de receber: quando ele responde 410, depois de 10 falhas seguidas, ou depois de 7 dias falhando sem nenhum sucesso. O aviso vai para o e-mail de avisos.
Pausar não guarda os eventos para depois. Enquanto a pausa durar, os eventos que acontecerem não são entregues, nem depois de retomar. Retomar volta a entregar só os eventos seguintes.
Religar não reenvia o que ficou para trás. As entregas canceladas pelo desligamento aparecem como Retida no histórico. Depois de religar, reenvie as que o parceiro precisa.
A Kamino tenta de novo sozinha antes de desistir. Uma entrega recusada é tentada até 8 vezes no total, em intervalos crescentes, por pouco mais de um dia. Enquanto houver tentativa agendada, ela aparece como Tentando e o reenvio manual não é oferecido. Esgotadas as tentativas, ela vira Esgotada.
Reenviar uma entrega que já foi aceita faz o parceiro recebê-la de novo. O reenvio usa o mesmo identificador de entrega; se o sistema do parceiro não descarta repetidos, ele processa duas vezes.
O histórico tem prazo. O detalhe das entregas fica 90 dias, e o corpo da resposta do parceiro, 30 dias.
O que não dá para desfazer: um segredo que ninguém guardou (a saída é rotacionar), a exclusão de um webhook (o segredo é destruído junto), a rotação por suspeita de vazamento (o antigo morre na hora) e o histórico que passou do prazo.
Por que o cadastro do webhook foi recusado, e o que fazer
Dê um nome que identifique o destino na lista e no histórico. O campo Nome ficou vazio. Escreva um nome, como o do sistema do parceiro.
O endereço precisa ser HTTPS. A Kamino não envia dado financeiro sem cifra. Troque o endereço para um que comece com
https://.Remova usuário e senha do endereço. A autenticação é pela assinatura do envio. Tire o usuário e a senha do endereço. O parceiro confere a origem pelo segredo.
Marque ao menos um evento. Sem evento, este endereço não receberia nada. Escolha os eventos que o parceiro precisa receber.
Escolha ao menos um domínio. Sem nenhum, este endereço não receberia nada. Na opção por domínio, marque pelo menos um domínio.
Compartilhar uma consulta do histórico de entregas
A busca por identificador e os filtros de assinatura e situação valem enquanto você consulta a tela. Eles não são gravados no endereço. Ao compartilhar o endereço, informe também o identificador da entrega que a outra pessoa deve procurar.
Perguntas frequentes sobre webhooks
Quantos webhooks posso ter ativos?
Até 10 ao mesmo tempo, por conta. Pausados e desativados pela plataforma não contam. Para ativar mais um, pause ou exclua outro.
Perdi o segredo do webhook. Como vejo de novo?
Não dá para ver de novo: o segredo aparece uma vez só. Rotacione o segredo no painel do webhook e entregue o valor novo ao parceiro.
Meu webhook foi desativado sozinho. O que faço?
A Kamino desativou porque o endereço respondeu 410, falhou 10 vezes seguidas ou passou 7 dias sem sucesso. Corrija o endereço, envie um evento de teste e clique em Reativar. Depois, reenvie as entregas Retidas que o parceiro precisa.
Por que não consigo reenviar uma entrega?
Se a entrega está como Tentando, ela ainda vai sair sozinha, e o reenvio manual não é oferecido. Se o webhook está pausado ou desativado, retome ou reative antes de reenviar.
O parceiro recebeu o mesmo evento duas vezes. Por quê?
A entrega pode chegar mais de uma vez, por exemplo num reenvio. Cada entrega tem um identificador que não muda entre as tentativas. O sistema do parceiro deve usar esse identificador para descartar o repetido.
Pausei o webhook. Os eventos do período chegam quando eu retomar?
Não. Os eventos que acontecem durante a pausa não são entregues. Retomar volta a entregar só os eventos seguintes.