Webhooks

Webhooks push real-time updates to your server when objects in Zapyd change state. Use them instead of polling. They are the recommended way to drive your integration logic.

Quick setup

Call POST /org/api/v1/organizations/api-webhooks with webhook_url. It must be public HTTPS. One URL receives every event type.

Verify every event

Check X-TIMESTAMP and X-SIGNATURE before you read the body. See Signature validation.

Acknowledge fast

Return 2xx within a few seconds, and do the work asynchronously. Zapyd treats any other response as a failed delivery.

Deduplicate

The same event can arrive more than once. Store id + event, and skip events you’ve already processed.

Event envelope

Every event has the same shape:

{
  "type": "PAYOUT",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "SUCCESS",
  "timestamp": "2026-09-30T10:00:00Z",
  "metadata": { "client_reference_id": "payout-001", "utr": "RATN12341234XYZ" }
}

Field	Meaning
`type`	The object that changed: `CUSTOMER`, `BANK`, `PAYIN`, `PAYOUT` or `EDD`
`id`	The object’s Zapyd ID (customer, bank account, payin, payout or EDD)
`event`	The status the object moved to
`timestamp`	When the change happened (ISO 8601)
`metadata`	Extra context for that event. Often empty on success

Webhooks tell you that something changed. For the full object, fetch it by id.

Signature validation

Every request includes two headers:

X-TIMESTAMP: 1752670745
X-SIGNATURE: ohmVyfuNup6eKWOdOZBBZut5CMPdPTfFSB/zDT/eXQo=

X-TIMESTAMP — Unix timestamp when the webhook was generated
X-SIGNATURE — HMAC-SHA256 of the request, Base64 encoded

Validate both on every incoming request. Reject anything with a stale timestamp or a signature mismatch. Webhooks are signed exactly like API requests, using your API key and secret: Base64(HMAC-SHA256(secret, apiKey + "|" + X-TIMESTAMP + "|" + canonicalBody)). See Authentication for the canonical body rules.

Python
Node.js

import base64
import hmac
import hashlib
import json
import time

def generate_hmac_signature(api_key, api_secret, timestamp, body=None):
    body = json.dumps(body or {}, sort_keys=True, separators=(",", ":"))
    message = f"{api_key}|{timestamp}|{body}".encode()
    signature = hmac.new(api_secret.encode(), message, hashlib.sha256).digest()
    return base64.b64encode(signature).decode()

def verify_hmac_signature(api_key, timestamp, signature, body, api_secret):
    if abs(time.time() - int(timestamp)) > 300:
        return False  # stale or replayed
    expected = generate_hmac_signature(api_key, api_secret, timestamp, body)
    return hmac.compare_digest(expected, signature)

Usage:

is_valid = verify_hmac_signature(
    api_key="your_api_key",
    api_secret="your_api_secret",
    timestamp=received_timestamp,
    signature=received_signature,
    body=webhook_body_dict,
)

if not is_valid:
    return 401  # reject

const crypto = require('crypto');

// Same canonical JSON as request signing: sorted keys at every level, no whitespace, non-ASCII escaped
function canonicalJson(value) {
  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
  if (value && typeof value === 'object') {
    return `{${Object.keys(value).sort()
      .map((k) => `${canonicalJson(k)}:${canonicalJson(value[k])}`)
      .join(',')}}`;
  }
  return JSON.stringify(value).replace(
    /[\u007f-\uffff]/g,
    (c) => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0')
  );
}

function verifyWebhook(apiKey, apiSecret, timestamp, signature, body) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = crypto
    .createHmac('sha256', apiSecret)
    .update(`${apiKey}|${timestamp}|${canonicalJson(body)}`)
    .digest('base64');
  const a = Buffer.from(expected);
  const b = Buffer.from(signature || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express: app.post('/webhook/zapyd', express.json(), (req, res) => {
//   const ok = verifyWebhook(API_KEY, API_SECRET, req.get('X-TIMESTAMP'), req.get('X-SIGNATURE'), req.body);
//   if (!ok) return res.sendStatus(401);
//   ...
// });

Always validate the signature before processing any webhook payload. Never trust the payload without verification.

Event catalog

Customer events

Fired when a customer’s KYC status changes.

Event	Description
`VERIFIED`	KYC passed. Customer can link banks and transact
`FAILED`	KYC failed or account suspended

Metadata:

failure_reason — present on FAILED. Values: DOCUMENT_VERIFICATION_FAILED, TAX_VERIFICATION_FAILED, ADDITIONAL_INFO_VERIFICATION_FAILED, KYC_FAILED

{
  "type": "CUSTOMER",
  "event": "FAILED",
  "id": "12348400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "failure_reason": "TAX_VERIFICATION_FAILED"
  }
}

Bank events

Fired when a bank account or UPI ID verification resolves.

Event	Description
`VERIFIED`	Bank account or UPI ID ready for orders
`FAILED`	Verification failed

Metadata:

failure_reason — present on FAILED. Values: ACCOUNT_TYPE_NRE, PENNY_DROP_FAILED, NAME_MISMATCH, BANK_RISK_CHECK_FAILED

{
  "type": "BANK",
  "event": "VERIFIED",
  "id": "12348400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {}
}

Payin events

Fired when a payin order changes state.

Event	Description
`SUCCESS`	Payment received, crypto released
`FAILED`	Payin failed
`REFUND_INITIATED`	Refund process started
`REFUNDED`	Fiat returned to source
`ON_HOLD`	Payment flagged and held for review

Metadata:

transaction_reference_id — present on SUCCESS. The bank reference (UTR for INR) of the customer’s payment
transaction_hash — present on SUCCESS. The on-chain transaction that delivered the crypto
failure_reason — present on FAILED. Values: INCORRECT_UTR, PAYMENT_NOT_RECEIVED, and others. See Failure Reason Reference
refund_reason — present on REFUND_INITIATED and REFUNDED. Values: INCORRECT_AMOUNT, PAYMENT_FROM_NON_WHITELISTED_ACCOUNT, THIRD_PARTY_PAYMENT

{
  "type": "PAYIN",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "SUCCESS",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "transaction_reference_id": "412345678901",
    "transaction_hash": "0x9f2c3b1a..."
  }
}

{
  "type": "PAYIN",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "FAILED",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "failure_reason": "INCORRECT_UTR"
  }
}

{
  "type": "PAYIN",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "REFUND_INITIATED",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "refund_reason": "INCORRECT_AMOUNT"
  }
}

Payout events

Fired when a payout order changes state.

Event	Description
`SUCCESS`	Funds delivered to beneficiary
`FAILED`	Payout failed
`REFUNDED`	Payout amount returned
`IN_REVIEW`	Payout held for compliance review or a request for information

Metadata:

client_reference_id — present on every payout event. Your reference from Create Payout, or null
utr — present on SUCCESS. The bank’s transfer reference (the UTR in India), usable for reconciliation
failure_reason — present on FAILED. Always the generic Payout failed; the detailed reason is not exposed
refund_reason — present on REFUNDED
reason — present on IN_REVIEW. Either Request for information (with an rfi_link the customer must complete) or Under compliance review

PROCESSING is not sent as a webhook. Poll Fetch Payout if you need it.

{
  "type": "PAYOUT",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "SUCCESS",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "client_reference_id": "payout-ref-001",
    "utr": "RATN12341234XYZ"
  }
}

{
  "type": "PAYOUT",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "IN_REVIEW",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {
    "client_reference_id": "payout-ref-001",
    "reason": "Request for information",
    "rfi_link": "https://..."
  }
}

EDD events

Fired when Enhanced Due Diligence verification resolves.

Event	Description
`VERIFIED`	EDD passed. The customer gets higher limits
`FAILED`	EDD failed. Standard limits remain

{
  "type": "EDD",
  "event": "VERIFIED",
  "id": "12348400-e29b-41d4-a716-446655440000",
  "timestamp": "2024-03-13T10:00:00Z",
  "metadata": {}
}

Get started

Onboard customers

Move money

Widget and no-code

Build and test

Markets

Coverage and help

Quick setup

Event envelope

Signature validation

Event catalog

Customer events

Bank events

Payin events

Payout events

EDD events

​Quick setup

​Event envelope

​Signature validation

​Event catalog

​Customer events

​Bank events

​Payin events

​Payout events

​EDD events

Quick setup

Event envelope

Signature validation

Event catalog

Customer events

Bank events

Payin events

Payout events

EDD events