Kobana
🇧🇷

Real-time notifications

Webhooks allow your application to receive automatic notifications whenever important events happen in Kobana, such as payments received, bank slips registered or transfers confirmed.

REST APIHMAC-SHA256Automatic retries
View API documentationView SDKs
Webhook log panel showing real-time event deliveries

How it works

1

Event occurs

in Kobana (e.g.: bank slip paid)

2

Kobana sends

HTTP POST request to your URL

3

Your application

processes the event and responds with 200 OK

4

Kobana confirms

successful delivery

Real-time notifications

Receive instant information about important events in your account.

HMAC signature

All requests are signed with HMAC-SHA256 to ensure authenticity.

Automatic retries

In case of failure, Kobana automatically resends the webhook up to 10 times.

Delivery history

Check the complete history of deliveries and status of each webhook.

Payload Structure

Each webhook sent by Kobana follows a standardized structure, making processing easy in your application.

Headers

Content-Type, X-Kobana-Event, X-Kobana-Signature

event

Event code and timestamp

resource

Type, internal ID and public UUID of the resource

data

Resource data at the time of the event

json
{
  "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": "John Smith",
    "status": "paid"
  }
}
bash
curl -X POST https://api.kobana.com.br/api/v2/data/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "name": "Payment Notifications",
      "url": "https://your-app.com/webhooks/kobana",
      "events": ["bank_billet.paid", "pix.paid"],
      "content_type": "application/json",
      "ssl_verification_enabled": true,
      "active": true
    }
  }'

Configuring Webhooks

Configure webhooks via API or through the Kobana dashboard in Settings > Webhooks.

nameDescriptive webhook name
urlDestination URL (HTTPS recommended)
eventsList of events that trigger the webhook
ssl_verification_enabledValidate SSL certificate (default: true)
activeWebhook active (default: true)

Security and Validation

All webhook requests include an HMAC-SHA256 signature in the X-Kobana-Signature header. Validate this signature before processing the event.

Ruby
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

# In 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
end
Python
import 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)

# In 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 '', 200
Node.js
const 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)
  );
}

// In 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
<?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);

Retries and Failures

When your application does not respond successfully (2xx), Kobana automatically resends the webhook with increasing intervals.

2xx responses are considered success
3xx, 4xx, 5xx responses trigger retry
30 second timeout per request
After 10 attempts, webhook is disabled
Retry Policy
Attempt 1Immediate
Attempt 21 minute
Attempt 35 minutes
Attempt 415 minutes
Attempt 51 hour
Attempt 66 hours
Attempt 7-1024 hours

Frequently asked questions

Ready to integrate?

Explore our complete documentation and start receiving webhooks today.

View API documentationView SDKs
Schedule