Webhooks

Um webhook avisa o seu sistema, por uma requisição HTTP, quando um evento acontece na Kobana: um boleto foi pago, uma cobrança Pix venceu, uma transferência foi confirmada. Você cadastra o endereço (URL) que vai receber os avisos e escolhe os eventos.

Esta página cobre o que se faz no painel. O formato das requisições, a lista completa de eventos e a validação da assinatura estão na referência técnica: Webhooks e Eventos de webhook.

Onde fica: Integrações > API > Webhooks (cadastro) e Integrações > API > Log de Webhooks (entregas).

Cadastrar um webhook

Na lista de webhooks, use Novo Webhook.

Campo	Obrigatório	Descrição
Nome	Não	Nome do webhook para identificação
Endereço para a requisição (URL)	Sim	Endereço que recebe as requisições, por exemplo https://example.com/callbacks/kobana
Eventos	Sim	Um ou mais eventos que disparam o webhook. Cada opção mostra a descrição e o código do evento. Há opções que agrupam todos os eventos de um recurso, como bank_billet.*, e os eventos customizados da conta aparecem como "Régua de Comunicação: ..."
Tipo da Requisição (content_type)	Sim	application/json (padrão) ou application/x-www-form-urlencoded
Limite de envios simultâneos	Sim	Quantas entregas podem ser processadas ao mesmo tempo para este webhook. O valor padrão de 10 atende a maioria dos casos
Tipo de autenticação	Não	Nenhuma, Basic Auth (Usuário e Senha), Bearer Token (Token) ou API Key (Nome do Header e Valor do Header). As credenciais vão em cada requisição
Verificação SSL Habilitada?	Não	Por padrão a Kobana verifica o certificado SSL do seu servidor
Ativar nas subcontas	Não	Só aparece em conta principal. Quando ativo, o webhook também recebe os eventos das subcontas
Ativo?	Não	A Kobana só envia requisições para webhooks ativos

Clique em Salvar Webhook. Logo após a criação, a Kobana envia ao endereço um evento de teste ping.

Regras da URL

• O endereço precisa começar com http:// ou https://. Prefira https://: para endereços sem SSL, a tela do webhook mostra um aviso recomendando o uso de https.
• Endereços locais (localhost, IPs de loopback e de rede privada) são recusados.

caution

Alterações nos eventos de um webhook já existente levam até 10 minutos para valer.

Chave secreta

Cada webhook tem uma chave secreta, usada para assinar as requisições. Com ela o seu sistema confirma que a requisição veio da Kobana; o cálculo da assinatura está na referência de webhooks.

• Na primeira vez que você abre o webhook, a janela Salve sua Chave Secreta agora mostra a chave completa. Ela é apresentada uma única vez: copie e guarde em local seguro antes de clicar em Já salvei!.
• Depois disso, o card Chave Secreta mostra a chave mascarada.
• Renovar Chave gera uma chave nova e mostra a janela de novo. A chave antiga deixa de valer: se ela já estiver em uso no seu sistema, a validação das requisições vai falhar até você trocar.

Webhooks criados pela API

Webhooks cadastrados pela API aparecem na lista, mas não podem ser alterados pelo painel nem ter a chave renovada ali (a tela mostra "Este webhook foi criado pela API e por esse motivo não pode ser alterado."). A chave secreta deles é entregue só na resposta da API.

Situação e saúde do webhook

A lista e a tela de cada webhook mostram um selo de situação:

Selo	Significado
Ativo	Recebendo eventos normalmente
Inativo	Desligado por um usuário
Degradado	Ativo, mas o endereço está há 3 dias ou mais sem aceitar entregas
Desativado automaticamente	Desligado pela Kobana porque o endereço parou de aceitar entregas

Quando o webhook está degradado ou desativado automaticamente, a tela dele mostra o bloco Saúde da entrega, com Situação, Sem entrega aceita (dias), Último sucesso, Último erro e, quando houver, Avisado em e Será desativado em. A regra exibida na tela: a Kobana avisa quando o endereço fica 7 dias sem aceitar nenhuma entrega e, se a desativação automática estiver ligada, desativa o webhook 7 dias depois do aviso.

Webhooks com problema também aparecem num alerta na página de boas-vindas do painel, com o link Ver webhooks com problema.

Para resolver:

• Corrigir e reativar: ajuste o endereço para que as entregas voltem a ser aceitas e marque o webhook como ativo de novo.
• Manter desativado: se o endereço não será mais usado, clique em Manter desativado (aparece em webhooks desativados automaticamente). Os avisos de saúde deixam de aparecer e o webhook continua desligado.

Log de Webhooks

Onde fica: Integrações > API > Log de Webhooks.

Cada evento enviado a um webhook vira uma entrega no log. A lista mostra os envios dos últimos 6 meses quando não há filtro de data.

Situação da entrega

Situação	Quando
Pendente	Aguardando o envio ou uma nova tentativa
Enviado	O endereço respondeu com código HTTP 1xx, 2xx ou 4xx, exceto 401 e 404
Falhou	O endereço respondeu 401, 404, 3xx ou 5xx, ou não respondeu (erro de conexão, tempo esgotado, erro de TLS, URL inválida)

Entregas que falham são tentadas de novo automaticamente, com intervalos crescentes. A exceção é a resposta 404: a Kobana não tenta de novo sozinha, mas o reenvio manual funciona.

Filtros

ID, ID do Recurso Base (por exemplo, o ID do boleto, para ver todas as entregas ligadas a ele), ID do Webhook, Criação (de / até), Falhas (de / até), Situação, Evento, Código de Resposta HTTP e Carteira.

O log filtrado pode ser exportado em CSV, XLSX ou ODS pelo botão Exportar.

Detalhe da entrega

A tela de uma entrega mostra o webhook, o evento, o objeto e a carteira, as datas (criação, primeiro envio, envio, resposta) e, lado a lado, a requisição enviada (Cabeçalhos da Requisição e Corpo da Requisição) e a resposta recebida (Cabeçalhos da Resposta e Corpo da Resposta). Em Ações:

• Reenviar notificação: envia o mesmo evento de novo para o webhook.
• Download Payload (JSON): baixa o conteúdo enviado.

Reenviar várias entregas

• Pela seleção: marque as entregas na lista e use Reenviar.
• Pelos filtros: filtre apenas por Código de Resposta HTTP, Evento e/ou período de Criação e use Reenviar Todos Filtrados. Esse botão só aparece quando os filtros aplicados são apenas esses; com outros filtros, use a seleção.

O reenvio é processado em segundo plano.

Notificar webhooks a partir de um evento

Em Administração > Históricos > Eventos, cada evento tem a ação Notificar webhooks, que cria novas entregas desse evento para todos os webhooks cadastrados com o código dele.

Excluir um webhook

Use Excluir no menu do webhook. A remoção é processada em segundo plano.

Permissões

No cadastro de usuários, módulo Automações:

• Contas Webhooks: Ações Básicas, Criar, Alterar e Excluir.
• Log de Webhooks: Ações Básicas, Reenviar e Fazer Download.

Pela API

Webhooks e entregas também podem ser gerenciados pela API: veja API v2 e API v1. Formato do payload, cabeçalhos e assinatura: Webhooks.