Skip to main content
Webhooks push event notifications to your server the moment something happens — no polling needed. Configure a single HTTPS endpoint to receive all events, then filter by event.type in your handler.
All webhook requests from Yativo include an X-Yativo-Signature header. Always verify this signature before processing any event.

​
Set Webhook URL

POST /business/webhook
​
url
string
required
Your HTTPS endpoint that will receive webhook events.
curl -X POST 'https://api.yativo.com/api/v1/business/webhook' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "url": "https://your-app.com/webhooks/yativo"
  }'

​
Get Webhook Configuration

GET /business/webhook

curl -X GET 'https://api.yativo.com/api/v1/business/webhook' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
Update Webhook URL

PUT /business/webhook
​
url
string
required
New destination URL.
curl -X PUT 'https://api.yativo.com/api/v1/business/webhook' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: unique-key-here' \
  -d '{
    "url": "https://your-app.com/webhooks/yativo-v2"
  }'

​
Webhook Event Types

Your endpoint receives POST requests with a JSON body containing an event.type field.
Event typeTriggered when
deposit.createdA new deposit is initiated
deposit.updatedA deposit status changes (e.g. pending → success)
deposit.completedA deposit is successfully completed
payout.updatedA payout status changes (e.g. completed or failed)
payout.completedA payout is successfully completed
customer.createdA new customer is created
customer.kyc.approvedA customer’s KYC is approved
customer.kyc.rejectedA customer’s KYC is rejected
virtual_account.depositA payment arrives at a virtual account
virtual_account.fundedA virtual account receives funds (settled)

​
Event Payloads

​
deposit.created

{
  "event.type": "deposit.created",
  "payload": {
    "id": "93df8440-b756-449c-b0e8-190e2bd8e2bf",
    "amount": 11,
    "gateway": "23",
    "currency": "CLP",
    "status": "pending",
    "deposit_currency": "USD",
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "created_at": "2026-04-01T17:19:56.000000Z"
  }
}

​
deposit.updated

{
  "event.type": "deposit.updated",
  "payload": {
    "id": "93df8440-b756-449c-b0e8-190e2bd8e2bf",
    "amount": 11,
    "gateway": "23",
    "currency": "CLP",
    "status": "success",
    "deposit_currency": "USD",
    "receive_amount": 2681,
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "updated_at": "2026-04-01T17:22:10.000000Z"
  }
}

​
payout.updated

{
  "event.type": "payout.updated",
  "payload": {
    "payout_id": "4533bb23-0f2d-4c00-8ce3-a2b4ab727b0e",
    "amount": "20.00",
    "currency": "ARS",
    "debit_wallet": "USD",
    "beneficiary_id": 5,
    "status": "completed",
    "created_at": "2026-04-01T21:32:46.000000Z",
    "updated_at": "2026-04-01T21:43:59.000000Z"
  }
}

​
customer.created

{
  "event.type": "customer.created",
  "payload": {
    "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
    "customer_name": "Jane Doe",
    "customer_email": "jane@example.com",
    "customer_phone": "+5511999999999",
    "customer_country": "BRA",
    "customer_status": "active",
    "customer_kyc_status": "approved",
    "created_at": "2026-04-01T16:15:20.000000Z"
  }
}

​
virtual_account.deposit

{
  "event.type": "virtual_account.deposit",
  "payload": {
    "amount": 1000,
    "currency": "BRL",
    "status": "completed",
    "credited_amount": 950,
    "transaction_type": "virtual_account_topup",
    "transaction_id": "TXNMP2HK81BHJ",
    "customer": {
      "customer_id": "da44a3e6-eb5d-429f-8d17-357aa5a6cdf2",
      "customer_name": "Jane Doe",
      "customer_kyc_status": "approved"
    },
    "source": {
      "account_number": "93405934593930",
      "sender_name": "Jane Doe",
      "transaction_fees": 50,
      "amount_received": 1000,
      "credited_amount": 950
    }
  }
}

​
Verifying Webhook Signatures

Every webhook request includes an X-Yativo-Signature header containing an HMAC SHA256 hex digest of the raw request body, signed with your webhook secret. Always verify this before trusting the payload. The signature is computed as: 
HMAC-SHA256(secret, JSON.stringify(payload))  →  hex string
Your webhook secret is available in your dashboard under Developer → Webhooks.
Never process a webhook event without first verifying its signature. Skipping this step exposes your endpoint to spoofed events.

​
Verification examples

const crypto = require('crypto');

app.post('/webhooks/yativo', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = process.env.YATIVO_WEBHOOK_SECRET;
  const receivedSignature = req.headers['x-yativo-signature'];

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(req.body) // raw Buffer — do NOT parse before this step
    .digest('hex');

  if (!crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(receivedSignature)
  )) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // safe to process
  res.status(200).send('OK');
});
Always use constant-time comparison (crypto.timingSafeEqual, hmac.compare_digest, hash_equals, etc.) — never a plain === or ==. Regular string comparison is vulnerable to timing attacks.
Use the raw request body bytes to compute the signature — not a re-serialized version of the parsed JSON. Parsing and re-stringifying can change whitespace or key order, causing signature mismatches.

​
Webhook Handler Example

Node.js (Express)
app.post('/webhooks/yativo', express.raw({ type: 'application/json' }), (req, res) => {
  // 1. Verify signature first (see above)
  verifySignature(req);

  const event = JSON.parse(req.body);

  switch (event['event.type']) {
    case 'deposit.updated':
      if (event.payload.status === 'success') {
        creditCustomer(event.payload.customer_id, event.payload.receive_amount);
      }
      break;

    case 'payout.updated':
      updatePayoutStatus(event.payload.payout_id, event.payload.status);
      break;

    case 'virtual_account.deposit':
      notifyCustomer(event.payload.customer.customer_id, event.payload.credited_amount);
      break;

    case 'customer.kyc.approved':
      enableCustomerFeatures(event.payload.customer_id);
      break;
  }

  res.status(200).send('OK');
});
Respond with a 2xx status within 10 seconds to acknowledge receipt. Failed deliveries are retried automatically.

​
Event Log

Retrieve all webhook events sent to your endpoint: 
GET /business/events/all
​
per_page
number
Results per page.
curl -X GET 'https://api.yativo.com/api/v1/business/events/all?per_page=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
Get Single Event

GET /business/events/show/{id}

curl -X GET 'https://api.yativo.com/api/v1/business/events/show/evt_01HX9KZMB3F7VNQP8R2WDGT4E5' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

​
API Request Logs

Audit all API calls made against your account: 
GET /business/logs/all
​
status
string
Filter by HTTP status code (e.g. 200, 400).
​
method
string
Filter by HTTP method (GET, POST, PUT, DELETE).
​
page
number
Page number.
​
per_page
number
Results per page.
curl -X GET 'https://api.yativo.com/api/v1/business/logs/all?method=POST&per_page=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'