Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.yativo.com/llms.txt

Use this file to discover all available pages before exploring further.

Set a URL to receive webhook notifications for events in your Yativo account. Yativo sends a POST request to your endpoint whenever a matching event occurs and signs every request with an X-Yativo-Signature header for verification. 
POST /business/webhook
Requires an Idempotency-Key header. To update an existing webhook, send PUT /business/webhook/{webhook} with the webhook ID returned from this endpoint.

​
Request Body

​
url
string
required
The HTTPS URL of your webhook endpoint. Must be publicly accessible.

​
Supported Events

EventDescription
deposit.createdA deposit was initiated
deposit.updatedA deposit status changed
deposit.completedA deposit was received and credited
payout.updatedA payout status changed
payout.completedA payout was delivered successfully
customer.createdA new customer was created
customer.kyc.approvedCustomer KYC was approved
customer.kyc.rejectedCustomer KYC was rejected
virtual_account.depositA payment arrived at a virtual account
virtual_account.fundedA virtual account received settled funds
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"
  }'

{
  "status": "success",
  "status_code": 201,
  "message": "Webhook configured successfully",
  "data": {
    "url": "https://your-app.com/webhooks/yativo",
    "secret": "whsec_a1b2c3d4e5f6...",
    "created_at": "2026-04-01T10:00:00.000000Z"
  }
}

​
Signature Verification

Every webhook delivery includes an X-Yativo-Signature header — an HMAC SHA256 hex digest of the raw request body signed with your webhook secret. Algorithm: 
X-Yativo-Signature = HMAC-SHA256(webhookSecret, rawRequestBody) → hex
Always verify the signature before processing any event. Use constant-time comparison to prevent timing attacks — never a plain string equality check.
Compute the HMAC over the raw request body bytes — not a re-serialized version of parsed JSON. Parsing and re-stringifying can change whitespace or key ordering, causing signature mismatches.

​
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)
    .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');
});