Webhooks - Yativo

Webhooks let Yativo push event data to your server the moment something happens, instead of you polling the API. When an event fires, Yativo sends an HTTP POST to your configured endpoint with a signed JSON payload.

Create a Webhook

POST /webhooks/create

string

required

A human-readable name for this webhook endpoint (e.g. “Production Deposits”).

string

required

The HTTPS or HTTP URL Yativo will POST events to.

string

required

A secret string you generate. Yativo uses it to sign every delivery so your server can verify the payload is genuine.

array

Optional allowlist of source IP addresses. When set, Yativo will only deliver events from these IPs. Leave empty to allow all.

cURL

curl -X POST https://crypto-api.yativo.com/api/v1/webhooks/create \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_name": "Production webhook",
    "webhook_url": "https://your-server.com/webhooks/yativo",
    "webhook_secret": "my_super_secret_string"
  }'

Response

{
  "status": "success",
  "status_code": "200",
  "message": "successful request",
  "data": {
    "_id": "664abc123def456789000001",
    "webhook_name": "Production webhook",
    "webhook_url": "https://your-server.com/webhooks/yativo",
    "user_id": "664abc123def456789000000",
    "status": "active",
    "createdAt": "2026-03-26T10:00:00.000Z"
  }
}

Store webhook_secret securely (e.g. in an environment variable). Use it to verify the X-Webhook-Signature header on every incoming delivery.

List Webhooks

GET /webhooks

cURL

curl -X GET https://crypto-api.yativo.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Update a Webhook

POST /webhooks/edit Pass webhook_id plus any fields you want to change. Omitted fields keep their current value.

string

required

The _id of the webhook to update.

string

Updated name.

string

Updated delivery URL.

string

Rotated secret.

array

Updated IP allowlist.

string

Set to "active" or "inactive" to pause/resume delivery.

cURL

curl -X POST https://crypto-api.yativo.com/api/v1/webhooks/edit \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_id": "664abc123def456789000001",
    "status": "inactive"
  }'

Delete a Webhook

POST /webhooks/delete

string

required

The _id of the webhook to delete.

cURL

curl -X POST https://crypto-api.yativo.com/api/v1/webhooks/delete \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_id": "664abc123def456789000001"
  }'

View Event Logs

GET /webhook/get-event-logs Returns a log of events processed through the webhook system.

cURL

curl -X GET https://crypto-api.yativo.com/api/v1/webhook/get-event-logs \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Signature Verification

Every webhook delivery includes an X-Webhook-Signature header. This is an HMAC-SHA256 signature of the raw request body, computed using your webhook_secret. Always verify the signature before processing events. This confirms the request genuinely came from Yativo and was not tampered with.

TypeScript / Node.js
Python
PHP

import crypto from 'crypto';
import { Request, Response } from 'express';

const WEBHOOK_SECRET = process.env.YATIVO_WEBHOOK_SECRET!;

export function verifyWebhook(req: Request, res: Response, next: Function) {
  const signature = req.headers['x-webhook-signature'] as string;
  const rawBody = (req as any).rawBody as Buffer; // ensure body parser preserves raw bytes

  if (!signature || !rawBody) {
    return res.status(400).json({ error: 'Missing signature or body' });
  }

  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  next();
}

import hmac
import hashlib
import os
from flask import request, abort

WEBHOOK_SECRET = os.environ['YATIVO_WEBHOOK_SECRET']

def verify_webhook():
    signature = request.headers.get('X-Webhook-Signature', '')
    raw_body = request.get_data()

    expected = hmac.new(
        WEBHOOK_SECRET.encode('utf-8'),
        raw_body,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401, 'Invalid signature')

<?php
function verifyWebhook(string $rawBody, string $secret): bool {
    $signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
    $expected = hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signature);
}

$rawBody = file_get_contents('php://input');
$secret = getenv('YATIVO_WEBHOOK_SECRET');

if (!verifyWebhook($rawBody, $secret)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($rawBody, true);
// process $event...

Webhook Payload Structure

All webhook payloads share the same envelope:

{
  "id": "evt_01abc123",
  "type": "deposit.confirmed",
  "created_at": "2026-03-26T10:05:00Z",
  "data": {
    // event-specific fields
  }
}

Best Practices

Respond with 2xx quickly

Your endpoint should return a 200 status within a few seconds. Do your heavy processing in the background. If Yativo does not receive a 2xx response, it will retry the event with exponential backoff.

Handle duplicates idempotently

Webhooks can be delivered more than once (e.g., after retries). Use the id field to deduplicate events in your database before processing.

Use HTTPS

Always use HTTPS endpoints in production so payloads cannot be intercepted in transit. The API accepts HTTP URLs but they should only be used for local development and testing.

Monitor the event log

Check GET /webhook/get-event-logs regularly to spot delivery failures before they become business problems.

​Create a Webhook

​List Webhooks

​Update a Webhook

​Delete a Webhook

​View Event Logs

​Signature Verification

​Webhook Payload Structure

​Best Practices

Create a Webhook

List Webhooks

Update a Webhook

Delete a Webhook

View Event Logs

Signature Verification

Webhook Payload Structure

Best Practices