Notificaciones en tiempo real
Los webhooks permiten que tu aplicación reciba notificaciones automáticas siempre que ocurran eventos importantes en Kobana, como pagos recibidos, boletos registrados o transferencias confirmadas.
Cómo funciona
Ocurre el evento
en Kobana (ej.: boleto pagado)
Kobana envía
request HTTP POST a tu URL
Tu aplicación
procesa el evento y responde con 200 OK
Kobana confirma
entrega exitosa
Recibe información instantánea sobre eventos importantes en tu cuenta.
Todas las requests están firmadas con HMAC-SHA256 para garantizar autenticidad.
En caso de falla, Kobana reenvía el webhook automáticamente hasta 10 veces.
Consulta el historial completo de entregas y el estado de cada webhook.
Estructura del Payload
Cada webhook enviado por Kobana sigue una estructura estandarizada, facilitando el procesamiento en tu aplicación.
Content-Type, X-Kobana-Event, X-Kobana-Signature
Código del evento y timestamp
Tipo, ID interno y UUID público del recurso
Datos del recurso en el momento del 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": "Juan Pérez",
"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": "Notificaciones de Pago",
"url": "https://tu-app.com/webhooks/kobana",
"events": ["bank_billet.paid", "pix.paid"],
"content_type": "application/json",
"ssl_verification_enabled": true,
"active": true
}
}'Configurar Webhooks
Configura webhooks vía API o a través del dashboard de Kobana en Ajustes > Webhooks.
nameNombre descriptivo del webhookurlURL de destino (HTTPS recomendado)eventsLista de eventos que disparan el webhookssl_verification_enabledValidar certificado SSL (por defecto: true)activeWebhook activo (por defecto: true)Seguridad y Validación
Todas las requests de webhook incluyen una firma HMAC-SHA256 en el header X-Kobana-Signature. Valida esta firma antes de procesar el 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
# En el 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, 'Firma inválida'
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)
# En 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 'Firma inválida', 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)
);
}
// En 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('Firma inválida');
}
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('Firma inválida');
}
$event = json_decode($payload, true);
processEvent($event);
http_response_code(200);Reintentos y Fallos
Cuando tu aplicación no responde con éxito (2xx), Kobana reenvía automáticamente el webhook con intervalos crecientes.
Preguntas frecuentes
¿Listo para integrar?
Explora nuestra documentación completa y empieza a recibir webhooks hoy mismo.