Handle VivaWallet Webhook Events with Full Type Safety

Manage VivaWallet webhook subscriptions, retrieve verification keys, create ISV webhooks, and route incoming events to the SDK’s webhook helper functions.

VivaWallet sends webhook events to your HTTPS endpoint when asynchronous payment, reporting, POS, marketplace, or connected-account events occur. The SDK separates webhook support into two surfaces:

• Webhook API modules — vivawallet.webhooks, marketplace.webhooks, and vivaIsv.webhook manage webhook subscriptions and verification keys.
• Receiver helper functions — package-root helpers build verification responses, verify Data Services signatures, extract identity/idempotency keys, and soft-validate event payloads.

Webhook Helpers

Use the detailed helper guide when implementing your webhook receiver. It documents every exported helper and when to use it.

A receiver should acknowledge Viva quickly. For slow work, return 200 OK after basic checks and process the event asynchronously.

Manage Merchant and Marketplace Subscriptions

Use vivawallet.webhooks for standard merchant webhook subscriptions. The Marketplace client exposes the same webhooks module for platform credentials.

const result = await vivawallet.webhooks.addSubscription({
  url: 'https://yourdomain.com/webhooks/vivawallet',
  secret: process.env.VIVA_WEBHOOK_SECRET!,
  events: ['SaleTransactionsFileGenerated'],
});

if (result.success && result.data) {
  console.log('Subscription ID:', result.data.subscriptionId);
}

List existing subscriptions:

const subs = await vivawallet.webhooks.listSubscriptions();

if (subs.success && subs.data) {
  const subscriptions = Array.isArray(subs.data) ? subs.data : [subs.data];

  for (const sub of subscriptions) {
    console.log(sub.subscriptionId, sub.url, sub.events);
  }
}

Update or delete a subscription by ID:

await vivawallet.webhooks.updateSubscription('subscription-id', {
  url: 'https://yourdomain.com/webhooks/vivawallet',
  secret: process.env.VIVA_WEBHOOK_SECRET!,
  events: ['SaleTransactionsFileGenerated'],
});

await vivawallet.webhooks.deleteSubscription('subscription-id');

Retrieve a Webhook Verification Key

Merchant and marketplace webhook verification uses a key returned by retrieveWebhookKey().

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

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

const key = keyResult.data;

For Marketplace integrations, call the same module on the platform client:

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

Use the key with buildVivaMerchantWebhookVerificationBody() or buildVivaMerchantWebhookVerificationResponse() when Viva verifies your endpoint. See Webhook Helpers for receiver examples.

Create ISV Webhooks

VivaISV exposes webhook.create(options) for ISV webhook setup. The alias webhooks points to the same module.

const result = await vivaIsv.webhook.create({
  url: 'https://yourdomain.com/webhooks/viva-isv',
  eventTypeId: 1796,
});

Retrieve the ISV verification key separately:

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

if (keyResult.success && keyResult.data) {
  console.log(keyResult.data.key);
}

Use buildVivaIsvWebhookVerificationBody() or buildVivaIsvWebhookVerificationResponse() for ISV endpoint verification.

Type Incoming Payloads

For lightweight payload typing, use VivaWebhookDatas<T> with a known event-data type.

import type {
  VivaWebhookDatas,
  SmartCheckoutWebhookEventDatas,
} from '@nkhind/vivawallet-sdk';

app.post('/webhooks/vivawallet', (req, res) => {
  const event: VivaWebhookDatas<SmartCheckoutWebhookEventDatas> = req.body;

  console.log(event.EventTypeId);
  console.log(event.EventData.TransactionId);

  res.sendStatus(200);
});

For new integrations, prefer the tolerant webhook types and helper functions documented in Webhook Helpers. They cover more Viva event families than the older SmartCheckoutWebhookEventDatas and ConnectedAccountWebhookEventDatas aliases.

Receiver Checklist

1. Answer Viva’s endpoint verification challenge with the right helper: merchant/marketplace responses use Key, ISV responses use key.
2. For signed Data Services webhooks, verify Viva-Signature-256 or Viva-Signature against the raw body before trusting the payload.
3. Extract identity and an idempotency key before processing so retries do not duplicate side effects.
4. Run the event-specific soft validator for the webhook family you are handling.
5. Persist the event or enqueue background work, then return 200 OK quickly when the delivery is accepted.

Official Webhook References

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