Webhook Helper Functions for VivaWallet Events

Use the SDK’s exported webhook helper functions to answer URL verification challenges, verify Data Services signatures, extract idempotency keys, and soft-validate Viva webhook payloads.

The SDK exports webhook helper functions from the package root. They are not methods on vivawallet.webhooks; use vivawallet.webhooks for subscription management, and import these helpers when building your webhook receiver.

import {
  buildVivaMerchantWebhookVerificationBody,
  buildVivaMerchantWebhookVerificationResponse,
  buildVivaIsvWebhookVerificationBody,
  buildVivaIsvWebhookVerificationResponse,
  verifyVivaDataServicesWebhookSignature,
  extractVivaWebhookIdentity,
  getVivaWebhookIdempotencyKey,
  validateVivaTransactionPaymentCreatedWebhook,
} from '@nkhind/vivawallet-sdk';

These helpers are intentionally tolerant. Viva webhook payloads can gain extra fields over time, and some fields differ between event families. The validators check the fields that matter for routing, reconciliation, idempotency, and business expectations; they do not perform strict schema validation.

Soft validation does not replace a server-side confirmation step when your workflow requires one. For payment state changes, you can still retrieve the order or transaction from Viva before mutating critical internal state.

URL verification helpers

When configuring webhooks, Viva can verify your endpoint by expecting your receiver to return a JSON body containing the webhook verification key. Merchant/Marketplace verification uses Key, while ISV verification uses key.

Retrieve the key with the client module first:

const keyResult = await vivawallet.webhooks.retrieveWebhookKey();

if (!keyResult.success || !keyResult.data) {
  throw new Error(keyResult.message);
}

buildVivaMerchantWebhookVerificationBody(key)

Builds only the JSON body expected by merchant and marketplace webhook verification.

const body = buildVivaMerchantWebhookVerificationBody(keyResult.data);
// { Key: '...' }

Use this when your framework already controls the HTTP status and headers.

buildVivaMerchantWebhookVerificationResponse(key)

Builds a framework-agnostic response object for merchant and marketplace webhook verification.

const response = buildVivaMerchantWebhookVerificationResponse(keyResult.data);

res.status(response.statusCode).set(response.headers).json(response.body);

The returned object has:

Field	Meaning
statusCode	Always 200
headers	Includes Content-Type: application/json
body	{ Key: key }

buildVivaIsvWebhookVerificationBody(key)

Builds only the JSON body expected by ISV webhook verification.

const keyResult = await vivaIsv.webhook.retrieveWebhookKey();

if (!keyResult.success || !keyResult.data) {
  throw new Error(keyResult.message);
}

const body = buildVivaIsvWebhookVerificationBody(keyResult.data.key);
// { key: '...' }

Use this with ISV webhook endpoints created through vivaIsv.webhook.create().

buildVivaIsvWebhookVerificationResponse(key)

Builds a framework-agnostic 200 JSON response for ISV webhook verification.

const response = buildVivaIsvWebhookVerificationResponse(keyResult.data.key);

res.status(response.statusCode).set(response.headers).json(response.body);

Data Services signature verification

verifyVivaDataServicesWebhookSignature(options)

Verifies signed Data Services webhook notifications, especially Sale Transactions file notifications. It uses the raw request body and Viva’s HMAC headers:

Header	Use
Viva-Signature-256	SHA-256 HMAC digest of the raw request body
Viva-Signature	SHA-1 HMAC digest of the raw request body
Viva-Delivery-Id	Delivery identifier returned in the result for logging/idempotency
Viva-Event	Event name returned in the result for logging/routing

const signature = verifyVivaDataServicesWebhookSignature({
  rawBody: req.rawBody,
  headers: req.headers,
  secret: process.env.VIVA_WEBHOOK_SECRET!,
});

if (!signature.valid) {
  console.warn('Invalid Viva Data Services signature', signature.issues);
  return res.sendStatus(401);
}

Pass algorithm: 'sha256' or algorithm: 'sha1' to require one algorithm. When omitted, the helper tries Viva-Signature-256 first and falls back to Viva-Signature when only the SHA-1 header is present.

Signature verification requires the raw request body before JSON parsing. Configure your HTTP framework to expose a Buffer, Uint8Array, or string containing the exact bytes Viva sent.

The result includes:

Field	Meaning
valid	true when the computed HMAC matches the Viva header
algorithm	sha256, sha1, or null when no usable signature is available
issues	Missing or mismatched field diagnostics
signature	Header signature used for the comparison, when present
deliveryId	Viva-Delivery-Id, when present
event	Viva-Event, when present

Identity and idempotency helpers

extractVivaWebhookIdentity(payload, headers?)

Extracts envelope identity fields and Data Services headers into one small object for logging, tracing, and routing.

const identity = extractVivaWebhookIdentity(req.body, req.headers);

console.log(identity.eventTypeId);
console.log(identity.messageId);
console.log(identity.deliveryId);
console.log(identity.retryCount);

It reads envelope fields such as EventTypeId, MessageId, CorrelationId, Created, RetryCount, RetryDelayInSeconds, RecipientId, and MessageTypeId. It also reads Viva-Delivery-Id and Viva-Event from headers when present.

Use this helper to add structured logs before branching on an event. It does not validate that the event is trusted.

getVivaWebhookIdempotencyKey(payload, headers?)

Builds a stable key you can use to deduplicate retries. The helper checks fields in priority order:

1. MessageId from the Viva envelope.
2. Viva-Delivery-Id from headers.
3. Stable event data identifiers such as TransactionId, OrderCode, TransferId, ObligationId, CaptureId, ConnectedAccountId, PersonId, SessionId, CommandId, or BankTransferId.

const idempotency = getVivaWebhookIdempotencyKey(req.body, req.headers);

if (!idempotency.success) {
  console.warn('No stable idempotency key', idempotency.warnings);
} else if (await alreadyProcessed(idempotency.key)) {
  return res.sendStatus(200);
}

The result tells you which field was used and whether the key came from the envelope, headers, or event data.

Soft validation pattern

Every validation helper returns VivaWebhookSoftValidationResult<T>:

const validation = validateVivaTransactionPaymentCreatedWebhook(req.body, {
  expectedOrderCode: '1234567890123456',
  expectedAmount: 1000,
});

if (!validation.valid) {
  console.warn(validation.issues);
}

if (validation.data) {
  console.log(validation.data.TransactionId);
}

The payload can be either the full Viva envelope ({ EventData: ... }) or the event data object itself. The optional expectations object lets you verify business values such as order code, amount, status, connected account, wallet, session, or command identifiers.

Decide your HTTP response policy deliberately. Signature failures usually warrant a non-200 response. Soft validation mismatches may be better acknowledged with 200 and quarantined internally if you do not want Viva to retry the same delivery.

Payment result validators

validateVivaPaymentResultWebhook(payload, expectations?)

Generic validator for payment-result style events. It requires OrderCode, TransactionId, StatusId, and Amount, and can compare CurrencyCode when expectedCurrencyCode is provided.

Use it when you intentionally handle several payment-result events through one branch.

validateVivaTransactionPaymentCreatedWebhook(payload, expectations?)

Semantic wrapper for Transaction Payment Created. Use it for successful Smart Checkout payment notifications.

const validation = validateVivaTransactionPaymentCreatedWebhook(req.body, {
  expectedOrderCode: order.orderCode,
  expectedAmount: order.amount,
});

validateVivaTransactionFailedWebhook(payload, expectations?)

Validates the same core payment fields and additionally requires ResponseEventId, which is useful for failed-payment diagnostics.

const validation = validateVivaTransactionFailedWebhook(req.body, {
  expectedOrderCode: order.orderCode,
});

validateVivaTransactionReversalCreatedWebhook(payload, expectations?)

Semantic wrapper for Transaction Reversal Created. Use it for reversal/refund-style transaction notifications where you expect the same core payment-result fields.

Order validator

validateVivaOrderUpdatedWebhook(payload, expectations?)

Validates Order Updated events. It requires OrderCode and IsCancelled, and can compare both with expectedOrderCode and expectedIsCancelled.

const validation = validateVivaOrderUpdatedWebhook(req.body, {
  expectedOrderCode: orderCode,
  expectedIsCancelled: true,
});

Use this event to detect order cancellation updates. Check validation.data?.IsCancelled before treating the order as cancelled.

Connected account validator

validateVivaAccountConnectionWebhook(payload, expectations?)

Validates account lifecycle events for Marketplace and ISV integrations, including Account Connected and Account Verification Status Changed payload shapes.

It requires ConnectedAccountId and can compare optional values such as PersonId, PlatformPersonId, WalletId, and Verified.

const validation = validateVivaAccountConnectionWebhook(req.body, {
  expectedConnectedAccountId: seller.accountId,
});

Use it when syncing seller or connected merchant onboarding status.

Marketplace and obligation validators

validateVivaTransferCreatedWebhook(payload, expectations?)

Validates Transfer Created events. It requires TransferId and can compare transaction, amount, currency, target wallet, target person, and transfer type values.

const validation = validateVivaTransferCreatedWebhook(req.body, {
  expectedTransferId: transferId,
  expectedAmount: 2500,
});

validateVivaObligationWebhook(payload, expectations?)

Validates deprecated obligation webhook payloads. It requires ObligationId and can compare CaptureId, amount, currency, target wallet, and target person values.

Use it only for integrations that still rely on Viva’s deprecated obligation flow.

POS and operational validators

validateVivaPosSessionWebhook(payload, expectations?)

Validates POS ECR session webhooks such as session-created and session-failed notifications. It checks SessionId, TransactionId, StatusId, Amount, and CurrencyCode, and requires at least one stable session identifier: SessionId or TransactionId.

const validation = validateVivaPosSessionWebhook(req.body, {
  expectedSessionId: sessionId,
});

validateVivaTransactionPriceCalculatedWebhook(payload, expectations?)

Validates Transaction Price Calculated payloads. It can compare TransactionId, OrderCode, Amount, and CurrencyCode when you pass expectations.

This helper is intentionally lightweight because the event can be used for pricing and fee-related flows where only a subset of fields may matter to your application.

validateVivaAccountTransactionWebhook(payload, expectations?)

Validates Account Transaction Created events. It requires TransactionId and can compare amount, currency, wallet, and account IDs.

const validation = validateVivaAccountTransactionWebhook(req.body, {
  expectedWalletId: walletId,
});

validateVivaBankTransferCommandWebhook(payload, expectations?)

Validates Command Bank Transfer Created and Command Bank Transfer Executed events. It checks command, bank transfer, transaction, amount, currency, and wallet fields. At least one of CommandId, BankTransferId, or TransactionId must be present.

const validation = validateVivaBankTransferCommandWebhook(req.body, {
  expectedCommandId: commandId,
});

Complete receiver sketch

import {
  extractVivaWebhookIdentity,
  getVivaWebhookIdempotencyKey,
  validateVivaTransactionPaymentCreatedWebhook,
} from '@nkhind/vivawallet-sdk';

app.post('/webhooks/viva', async (req, res) => {
  const identity = extractVivaWebhookIdentity(req.body, req.headers);
  const idempotency = getVivaWebhookIdempotencyKey(req.body, req.headers);

  if (idempotency.success && await alreadyProcessed(idempotency.key)) {
    return res.sendStatus(200);
  }

  if (identity.eventTypeId === 1796) {
    const validation = validateVivaTransactionPaymentCreatedWebhook(req.body);

    if (!validation.valid) {
      await quarantineWebhook({ identity, issues: validation.issues, body: req.body });
      return res.sendStatus(200);
    }

    await markOrderPaid(validation.data!.OrderCode, validation.data!.TransactionId);
  }

  return res.sendStatus(200);
});

Official webhook references

• Webhook event index
• Setting up webhooks
• Sale Transactions signed webhook
• Transaction Payment Created
• Order Updated