Notificações em tempo real
Webhooks permitem que sua aplicação receba notificações automáticas sempre que eventos importantes acontecem na Kobana, como pagamentos recebidos, boletos registrados ou transferências confirmadas.
Como funciona
Evento ocorre
na Kobana (ex: boleto pago)
Kobana envia
requisição HTTP POST para sua URL
Sua aplicação
processa o evento e responde com 200 OK
Kobana confirma
entrega bem-sucedida
Receba informações instantâneas sobre eventos importantes na sua conta.
Todas as requisições são assinadas com HMAC-SHA256 para garantir autenticidade.
Em caso de falha, a Kobana reenvia o webhook automaticamente até 10 vezes.
Consulte o histórico completo de entregas e status de cada webhook.
Estrutura do Payload
Cada webhook enviado pela Kobana segue uma estrutura padronizada, facilitando o processamento em sua aplicação.
Content-Type, X-Kobana-Event, X-Kobana-Signature
Código e timestamp do evento
Tipo, ID interno e UUID público do recurso
Dados do recurso no momento do evento
{
"event": {
"code": "bank_billet.paid",
"occurred_at": "2025-01-15T10:30:00Z"
},
"resource": {
"type": "BankBillet",
"id": 123456,
"uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"data": {
"amount": 150.50,
"paid_amount": 150.50,
"paid_at": "2025-01-15T10:30:00Z",
"customer_person_name": "João da Silva",
"status": "paid"
}
}curl -X POST https://api.kobana.com.br/api/v2/data/webhooks -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
"webhook": {
"name": "Notificações de Pagamento",
"url": "https://sua-app.com.br/webhooks/kobana",
"events": ["bank_billet.paid", "pix.paid"],
"content_type": "application/json",
"ssl_verification_enabled": true,
"active": true
}
}'Configurando Webhooks
Configure webhooks via API ou pelo painel da Kobana em Configurações > Webhooks.
nameNome descritivo do webhookurlURL de destino (HTTPS recomendado)eventsLista de eventos que acionam o webhookssl_verification_enabledValidar certificado SSL (padrão: true)activeWebhook ativo (padrão: true)Segurança e Validação
Todas as requisições de webhook incluem uma assinatura HMAC-SHA256 no header X-Kobana-Signature. Valide essa assinatura antes de processar o evento.
require 'openssl'
def valid_signature?(payload, signature, secret_key)
expected = 'sha256=' + OpenSSL::HMAC.hexdigest('SHA256', secret_key, payload)
Rack::Utils.secure_compare(expected, signature)
end
# No controller
post '/webhooks/kobana' do
payload = request.body.read
signature = request.env['HTTP_X_KOBANA_SIGNATURE']
unless valid_signature?(payload, signature, ENV['KOBANA_WEBHOOK_SECRET'])
halt 401, 'Invalid signature'
end
event = JSON.parse(payload)
ProcessWebhookJob.perform_later(event)
status 200
endimport hmac
import hashlib
def valid_signature(payload, signature, secret_key):
expected = 'sha256=' + hmac.new(
secret_key.encode(),
payload.encode(),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, signature)
# No Flask
@app.route('/webhooks/kobana', methods=['POST'])
def webhook():
payload = request.data.decode()
signature = request.headers.get('X-Kobana-Signature')
if not valid_signature(payload, signature, os.environ['KOBANA_WEBHOOK_SECRET']):
return 'Invalid signature', 401
event = request.json
process_event(event)
return '', 200const crypto = require('crypto');
function validSignature(payload, signature, secretKey) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secretKey)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
);
}
// No Express
app.post('/webhooks/kobana', (req, res) => {
const payload = JSON.stringify(req.body);
const signature = req.headers['x-kobana-signature'];
if (!validSignature(payload, signature, process.env.KOBANA_WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
processEvent(req.body);
res.sendStatus(200);
});<?php
function validSignature($payload, $signature, $secretKey) {
$expected = 'sha256=' . hash_hmac('sha256', $payload, $secretKey);
return hash_equals($expected, $signature);
}
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_KOBANA_SIGNATURE'] ?? '';
if (!validSignature($payload, $signature, getenv('KOBANA_WEBHOOK_SECRET'))) {
http_response_code(401);
exit('Invalid signature');
}
$event = json_decode($payload, true);
processEvent($event);
http_response_code(200);Retentativas e Falhas
Quando sua aplicação não responde com sucesso (2xx), a Kobana reenvia o webhook automaticamente com intervalos crescentes.
Perguntas frequentes
Pronto para integrar?
Explore nossa documentação completa e comece a receber webhooks hoje.