Webhooks

Webhooks push event notifications to your server as payments move through their lifecycle. ZendFi signs every webhook delivery with HMAC-SHA256 so you can verify authenticity, and retries failed deliveries with exponential backoff.

How It Works

Webhook Configuration

Set your webhook URL in the ZendFi Dashboard or during zendfi init with the CLI. Every webhook registered under your merchant account receives all event types.

Event Types

All events your webhook endpoint can receive:

Payment Events

Event	Description
`PaymentCreated`	A new payment has been created
`PaymentConfirmed`	Payment confirmed on-chain
`PaymentFailed`	Payment failed or was rejected
`PaymentExpired`	Payment expired before completion
`FraudFlagRaised`	Payment flagged by fraud controls
`FraudPaymentBlocked`	Payment blocked by fraud controls

Refund Events

Event	Description
`RefundInitiated`	Refund request created
`RefundCompleted`	Refund transfer completed
`RefundFailed`	Refund transfer failed

Dispute Events

Event	Description
`DisputeOpened`	Customer opened a dispute
`DisputeResponded`	Merchant submitted a dispute response
`DisputeResolved`	Dispute resolved by merchant/admin action

Payment Intent Events

Event	Description
`PaymentIntentCreated`	Payment intent created
`PaymentIntentRequiresPayment`	Intent awaiting customer payment
`PaymentIntentSucceeded`	Intent completed successfully
`PaymentIntentCanceled`	Intent was cancelled
`PaymentIntentFailed`	Intent failed

Settlement Events

Event	Description
`SettlementCompleted`	Funds settled to merchant wallet
`SettlementFailed`	Settlement transfer failed

Withdrawal Events

Event	Description
`WithdrawalInitiated`	Withdrawal request submitted
`WithdrawalCompleted`	Withdrawal confirmed on-chain
`WithdrawalFailed`	Withdrawal failed

Sub-Account Lifecycle Events

Event	Description
`SubAccountCreated`	A sub-account was created
`SubAccountDelegationTokenMinted`	Delegation token minted for a sub-account
`SubAccountFrozen`	Sub-account was frozen
`SubAccountUnfrozen`	Sub-account was unfrozen and reactivated
`SubAccountClosed`	Sub-account was closed

Subscription Events

Event	Description
`SubscriptionCreated`	New subscription started
`SubscriptionCancelled`	Subscription cancelled
`SubscriptionRenewed`	Subscription successfully renewed
`SubscriptionPaymentFailed`	Subscription renewal payment failed

Installment Events

Event	Description
`InstallmentPaid`	Installment payment confirmed
`InstallmentLate`	Installment past due date
`InstallmentDefaulted`	Installment defaulted (past grace period)
`InstallmentPlanCompleted`	All installments paid

Payment Link Events

Event	Description
`PaymentLinkCreated`	Payment link generated
`PaymentLinkUsed`	Customer paid via payment link

Invoice Events

Event	Description
`InvoiceCreated`	Invoice created
`InvoiceSent`	Invoice emailed to customer
`InvoicePaid`	Invoice payment confirmed

Webhook Payload Structure

Every webhook delivery is an HTTP POST with a JSON body:

{
  "event": "PaymentConfirmed",
  "payment": {
    "id": "pay_test_abc123",
    "merchant_id": "merch_xyz789",
    "amount_usd": 49.99,
    "status": "confirmed",
    "transaction_signature": "5UfDuKxNgqH...",
    "customer_wallet": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "payment_token": "USDC",
    "mode": "test",
    "description": "Order #1234",
    "metadata": {"order_id": "1234"},
    "splits": null,
    "created_at": "2026-03-01T12:00:00Z",
    "expires_at": "2026-03-01T12:15:00Z"
  },
  "settlement": null,
  "withdrawal": null,
  "refund": null,
  "dispute": null,
  "fraud": null,
  "timestamp": "2026-03-01T12:05:00Z"
}

Payload Fields

event

string

The event type (see table above).

payment

object

Payment data. Present for payment, payment link, installment, and subscription events.Key fields: id, merchant_id, amount_usd, status, transaction_signature, customer_wallet, payment_token, mode, description, metadata, splits, created_at, expires_at.

settlement

object

Settlement data. Present for SettlementCompleted and SettlementFailed.Key fields: id, payment_id, merchant_id, amount_usd, settlement_token, settlement_amount, transaction_signature, merchant_wallet, status.

withdrawal

object

Withdrawal data. Present for withdrawal events.Key fields: id, merchant_id, sub_account_id, delegation_token_id, automation_token_id, signing_grant_id, auth_mode, to_address, from_address, amount, token, transaction_signature, status, is_bank_withdrawal, offramp_order_id, paj_order_id, bank_account_number, bank_name.

sub_account

object

Sub-account lifecycle payload. Present for SubAccountCreated, SubAccountDelegationTokenMinted, SubAccountFrozen, and SubAccountClosed.Key fields: id, external_id, merchant_id, label, wallet_address, created_at, reference_id, metadata.

refund

object

Refund data. Present for RefundInitiated, RefundCompleted, RefundFailed.Key fields: id, payment_id, merchant_id, amount_usd, status, reason, initiated_by, transaction_signature, customer_wallet, customer_email, created_at, completed_at.

dispute

object

Dispute data. Present for DisputeOpened, DisputeResponded, DisputeResolved.Key fields: id, payment_id, refund_id, merchant_id, customer_email, customer_wallet, dispute_type, status, description, opened_at, resolved_at.

fraud

object

Fraud data. Present for fraud events.Key fields: payment_id, merchant_id, fraud_score, blocked, flags.

timestamp

string

ISO 8601 timestamp of when the event was generated.

Signature Verification

Every webhook includes a x-zendfi-signature header with the format:

t=1709294700,v1=5d41402abc4b2a76b9719d911017c592...

The signature is computed as:

Create the signed payload: {timestamp}.{json_body}
Compute HMAC-SHA256 using your webhook secret
Compare the hex-encoded result to the v1= value

Verification Examples

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const parts = signature.split(',');
  if (parts.length !== 2) return false;

  const timestamp = parts[0].replace('t=', '');
  const providedSig = parts[1].replace('v1=', '');

  // Reject signatures older than 5 minutes
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (age > 300 || age < -60) return false;

  const signedPayload = `${timestamp}.${payload}`;
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expectedSig),
    Buffer.from(providedSig)
  );
}

import hmac, hashlib, time

def verify_webhook(payload: str, signature: str, secret: str) -> bool:
    parts = signature.split(",")
    if len(parts) != 2:
        return False

    timestamp = parts[0].replace("t=", "")
    provided_sig = parts[1].replace("v1=", "")

    age = int(time.time()) - int(timestamp)
    if age > 300 or age < -60:
        return False

    signed_payload = f"{timestamp}.{payload}"
    expected_sig = hmac.new(
        secret.encode(), signed_payload.encode(), hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected_sig, provided_sig)

Using the SDK

The SDK provides built-in verification:

import { ZendFiClient } from '@zendfi/sdk';

const zendfi = new ZendFiClient({ apiKey: 'zfi_test_...' });

const isValid = zendfi.verifyWebhook(rawBody, signatureHeader);

Or use the framework-specific handlers:

Express
Next.js

import { createExpressWebhookHandler } from '@zendfi/sdk/webhooks/express';

app.post('/webhooks/zendfi',
  express.raw({ type: 'application/json' }),
  createExpressWebhookHandler({
    secret: process.env.ZENDFI_WEBHOOK_SECRET!,
    onPaymentConfirmed: (payment) => {
      console.log('Payment confirmed:', payment.id);
    },
    onPaymentFailed: (payment) => {
      console.log('Payment failed:', payment.id);
    },
  })
);

import { createNextJsWebhookHandler } from '@zendfi/sdk/webhooks/nextjs';

export const POST = createNextJsWebhookHandler({
  secret: process.env.ZENDFI_WEBHOOK_SECRET!,
  onPaymentConfirmed: (payment) => {
    // Fulfill the order
  },
});

Delivery and Retries

ZendFi uses exponential backoff for failed webhook deliveries:

Attempt	Delay	Total Elapsed
1	Immediate	0s
2	30 seconds	30s
3	2 minutes	~2.5 min
4	10 minutes	~12.5 min
5	1 hour	~1 hour

After all retry attempts are exhausted, the webhook is marked as exhausted and moved to the dead letter queue. You will receive an email alert if you have notifications enabled.

Webhook Statuses

Status	Description
`pending`	Queued for delivery
`delivered`	Successfully delivered (received 2xx response)
`failed`	Delivery attempt failed, will retry
`exhausted`	All retry attempts failed

List Webhook Events

GET /api/v1/webhooks

Returns all webhook events for the authenticated merchant.

const events = await zendfi.listWebhookEvents();

Retry a Webhook

POST /api/v1/webhooks/{id}/retry

Manually retry a failed or exhausted webhook delivery.

string

required

Webhook event ID.

curl -X POST https://api.zendfi.tech/api/v1/webhooks/wh_abc123/retry \
  -H "Authorization: Bearer zfi_test_your_key"

Verify Webhook Configuration

POST /api/v1/webhooks/verify

Test your webhook signature verification by sending a payload and signature. Returns whether the signature is valid. Useful during development.

payload

string

required

The raw webhook payload body.

signature

string

required

The signature string to verify (t=...,v1=...).

Response

{
  "valid": true,
  "message": "Webhook signature is valid",
  "timestamp_age_seconds": 12
}

Best Practices

Always verify signatures

Never trust webhook payloads without verifying the HMAC signature. This prevents spoofed events from triggering actions in your system.

Return 200 quickly

Process webhook data asynchronously. Return a 200 response immediately and handle the business logic in a background job. ZendFi interprets slow responses as failures.

Handle duplicate deliveries

Webhooks may be delivered more than once. Use the payment.id or event ID for idempotency checks before processing.

Use raw body for verification

Parse the JSON body only after verifying the signature against the raw string. Parsing and re-serializing can change whitespace and break the signature check.

​Webhooks

​How It Works

​Webhook Configuration

​Event Types

​Payment Events

​Refund Events

​Dispute Events

​Payment Intent Events

​Settlement Events

​Withdrawal Events

​Sub-Account Lifecycle Events

​Subscription Events

​Installment Events

​Payment Link Events

​Invoice Events

​Webhook Payload Structure

​Payload Fields

​Signature Verification

​Verification Examples

​Using the SDK

​Delivery and Retries

​Webhook Statuses

​List Webhook Events

​Retry a Webhook

​Verify Webhook Configuration

​Response

​Best Practices

Webhooks

How It Works

Webhook Configuration

Event Types

Payment Events

Refund Events

Dispute Events

Payment Intent Events

Settlement Events

Withdrawal Events

Sub-Account Lifecycle Events

Subscription Events

Installment Events

Payment Link Events

Invoice Events

Webhook Payload Structure

Payload Fields

Signature Verification

Verification Examples

Using the SDK

Delivery and Retries

Webhook Statuses

List Webhook Events

Retry a Webhook

Verify Webhook Configuration

Response

Best Practices