Skip to main content
Webhooks push real-time event notifications to your server when something happens in your Oak account — a payment completes, a refund is issued, a transfer lands, etc. Register an HTTPS endpoint, store the signing secret, and verify incoming payloads to keep your system in sync without polling. 
import { createOakClient, createWebhookService } from '@oaknetwork/payments-sdk';

const client = createOakClient({ ... });
const webhooks = createWebhookService(client);

​
Methods

MethodDescription
register(webhook)Register a new webhook
list()List all registered webhooks
get(id)Get a webhook by ID
update(id, webhook)Update a webhook
toggle(id)Toggle a webhook on or off
delete(id)Delete a webhook
listNotifications(params?)List webhook notifications
getNotification(id)Get a specific notification

​
Register a webhook

const result = await webhooks.register({
  url: 'https://your-server.com/webhooks/oak',
  description: 'Production webhook',
});

if (result.ok) {
  const webhook = result.value.data;
  console.log('Webhook ID:', webhook.id);
  console.log('Secret:', webhook.secret); // store this — used to verify signatures
}
The secret is only returned on register. Store it securely — you need it to verify incoming webhook signatures.

​
List webhooks

const result = await webhooks.list();

if (result.ok) {
  for (const wh of result.value.data) {
    console.log(`${wh.id} — ${wh.url} — active: ${wh.is_active}`);
  }
}

​
Update a webhook

const result = await webhooks.update('wh_abc123', {
  url: 'https://your-server.com/webhooks/oak-v2',
  description: 'Updated endpoint',
});

​
Toggle a webhook

Enable or disable a webhook without deleting it: 
const result = await webhooks.toggle('wh_abc123');

if (result.ok) {
  console.log('Active:', result.value.data.is_active);
}

​
Delete a webhook

const result = await webhooks.delete('wh_abc123');

if (result.ok) {
  console.log('Deleted:', result.value.data.success);
}

​
Notifications

List all notifications that have been sent to your webhooks: 
const result = await webhooks.listNotifications({
  limit: 20,
  offset: 0,
});

if (result.ok) {
  console.log(`Total notifications: ${result.value.data.count}`);
  for (const n of result.value.data.notification_list) {
    console.log(`  ${n.id} — event: ${n.event} — ack: ${n.is_acknowledged}`);
  }
}
Get a specific notification: 
const result = await webhooks.getNotification('notif_abc123');

if (result.ok) {
  console.log('Event:', result.value.data.event);
  console.log('Category:', result.value.data.category);
  console.log('Payload:', result.value.data.data);
}

​
Signature verification

The SDK exports utilities to verify incoming webhook signatures using HMAC-SHA256 with timing-safe comparison.

​
Signature header format

The webhook signature is sent in the Oak-Signature header with the format: 
Oak-Signature: t=<timestamp>,v1=<signature>
The SDK parses the header by key prefix (not position), so the field order does not matter.

​
Verify a signature

import { verifyWebhookSignature } from '@oaknetwork/payments-sdk';

const isValid = verifyWebhookSignature(
  JSON.stringify(req.body),                  // raw payload string
  req.headers['oak-signature'],              // signature from Oak-Signature header
  process.env.WEBHOOK_SECRET!,              // secret from register()
);

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

​
Verify and parse in one step

parseWebhookPayload combines signature verification with JSON parsing, returning a Result: 
import { parseWebhookPayload } from '@oaknetwork/payments-sdk';

const result = parseWebhookPayload<PaymentEvent>(
  JSON.stringify(req.body),
  req.headers['oak-signature'],
  process.env.WEBHOOK_SECRET!,
);

if (!result.ok) {
  return res.status(result.error.status).json({ error: result.error.message });
}

const event = result.value;
switch (event.event) {
  case 'payment.completed':
    // handle payment completion
    break;
  case 'payment.failed':
    // handle payment failure
    break;
}

res.json({ received: true });

​
Express.js example

import express from 'express';
import { parseWebhookPayload } from '@oaknetwork/payments-sdk';

const app = express();

app.post('/webhooks/oak', express.raw({ type: 'application/json' }), (req, res) => {
  const result = parseWebhookPayload(
    req.body.toString(),
    req.headers['oak-signature'] as string,
    process.env.WEBHOOK_SECRET!,
  );

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

  // Handle the verified event
  console.log('Received event:', result.value.event);
  res.json({ received: true });
});
Always verify webhook signatures before processing payloads. Use express.raw() (not express.json()) to preserve the raw body for signature verification.

​
Webhook data types

​
RegisterRequest

FieldTypeRequiredDescription
urlstringYesThe URL to receive webhook events
descriptionstringNoHuman-readable description

​
Webhook data (response)

FieldTypeDescription
idstringWebhook ID
urlstringRegistered URL
descriptionstringDescription
secretstringSigning secret (only on register)
is_activebooleanWhether the webhook is active

​
Notification

FieldTypeDescription
idstringNotification ID
eventstring | nullEvent type
categorystring | nullEvent category
dataanyEvent payload
is_acknowledgedbooleanWhether the notification was acknowledged

​
Event types

The Webhook.EventType type includes 75+ events across these namespaces:
  • customer.* — customer lifecycle events
  • provider_registration.* — provider registration events
  • payment.* — payment lifecycle events
  • transaction.* — transaction events
  • dispute.* — dispute events
  • kyc.* — KYC verification events
  • transfer.* — transfer events
  • sell.* — sell (off-ramp) events
  • buy.* — buy (on-ramp) events

​
Event categories

The Webhook.Category type includes 12 categories: payment_lifecycle, provider_registration_lifecycle, and others that group related events for filtering and routing.