Webhooks & Events

Time: ~10 minutes | Difficulty: Beginner Use the TagadaPay Node SDK to register HTTPS endpoints for real-time notifications, verify deliveries cryptographically, and query the event log for debugging and analytics.

What webhooks are (and why use them)

Webhooks are HTTP callbacks TagadaPay sends to your server when something happens on the platform — for example, a successful payment or a subscription change. Your endpoint receives a JSON payload so you can update your database, trigger fulfillment, notify internal tools, or sync with Zapier/n8n without polling the API.

Webhooks run asynchronously after the triggering action. Design your handler to respond quickly (e.g. validate the signature, enqueue work, return 2xx). Heavy work should happen in a background job.

Create a webhook

Register a URL and the event types you care about. The API returns the endpoint id, URL, signing secret, subscribed types, and whether the endpoint is enabled.

import Tagada from '@tagadapay/node-sdk';

const tagada = new Tagada('your-api-key');

const webhook = await tagada.webhooks.create({
  storeId: 'store_...',
  url: 'https://api.example.com/webhooks/tagada',
  eventTypes: ['order/paid', 'subscription/created', 'subscription/canceled'],
  description: 'Production notifications',
});

// { id, url, secret, eventTypes, enabled, storeId, createdAt, ... }
console.log(webhook.id, webhook.secret);

Store webhook.secret securely (environment variable or secrets manager). It is returned when you create the endpoint and is required to verify that payloads really came from TagadaPay.

The signing secret

Each webhook endpoint has a unique secret. TagadaPay uses it to compute an HMAC-SHA256 signature over the raw JSON body of each delivery. Your server must verify that signature before trusting the payload.

Event type strings in eventTypes must exactly match the names listed below (slash format like order/paid). The SDK validates event types at build time via TypeScript and at runtime — passing an invalid type will throw an error immediately.

List webhooks

const endpoints = await tagada.webhooks.list('store_...');
// Webhook[]

Delete a webhook

const { success, id } = await tagada.webhooks.del('wh_...');

Available event types

All webhook event types use the slash format (category/event). These are the only valid values accepted by the eventTypes field.

Order events

Event type	Description
`order/paid`	Order successfully paid — trigger fulfillment or CRM updates
`order/created`	Order record created
`order/refunded`	Order refunded
`order/failed`	Order payment failed
`order/upsellStarted`	Post-purchase upsell flow initiated
`order/paymentInitiated`	Payment process started for an order

Checkout events

Event type	Description
`checkout/initiated`	Checkout session started
`checkout/emailValidated`	Customer email validated during checkout

Payment events

Event type	Description
`payment/created`	Payment record created
`payment/succeeded`	Payment completed successfully
`payment/failed`	Payment attempt failed
`payment/refunded`	Payment refunded
`payment/authorized`	Payment authorized (not yet captured)
`payment/rejected`	Payment rejected by processor or fraud rules

Subscription events

Event type	Description
`subscription/created`	New subscription started
`subscription/canceled`	Subscription canceled
`subscription/paused`	Subscription paused
`subscription/resumed`	Subscription resumed
`subscription/pastDue`	Subscription payment past due
`subscription/rebillUpcoming`	Upcoming rebill notification
`subscription/rebillSucceeded`	Rebill charge succeeded
`subscription/rebillDeclined`	Rebill charge declined
`subscription/cancelScheduled`	Cancellation scheduled for end of period
`subscription/rebillCaptureFailed`	Rebill capture failed

Funnel events

Event type	Description
`funnel/sessionStarted`	Funnel session started
`funnel/sessionCompleted`	Funnel session completed
`funnel/stepEntered`	Visitor entered a funnel step
`funnel/stepViewed`	Funnel step viewed
`funnel/stepExited`	Visitor exited a funnel step
`funnel/converted`	Funnel conversion recorded
`funnel/customEvent`	Custom funnel event fired
`funnel/sessionAbandoned`	Funnel session abandoned

Club events

Event type	Description
`club/membershipActivated`	Club membership activated
`club/membershipDeactivated`	Club membership deactivated

Security events

Event type	Description
`security/abuseDetected`	Abuse or fraud detected

The SDK and API reject any event type not in this list. If you pass an invalid type like order.paid (dot format) or s_order_paid (internal format), you will receive a validation error.

Events API (query & analytics)

Use the Events resource to audit activity, build dashboards, or debug webhook payloads.

Recent events

const recent = await tagada.events.recent(25);
// AppEvent[] — includes eventType, createdAt, payload, storeId, ...

Statistics

const stats = await tagada.events.statistics({ storeId: 'store_...' });
// { totalEvents, eventsByType, processedCount, unprocessedCount }

List with filters and pagination

const { data, total, page, pageSize, hasMore } = await tagada.events.list({
  pagination: { page: 1, pageSize: 50 },
  sortBy: { field: 'appEvents.createdAt', direction: 'desc' },
  filters: {
    'stores.id': ['store_...'],
    // Event types here are often internal analytics ids (e.g. s_order_paid) — see Note below
    'appEvents.eventType': ['s_order_paid'],
  },
});

Optional filters include date ranges on appEvents.createdAt / appEvents.processedAt, customer.email, appEvents.draft, and free-text search.

Webhook subscriptions use slash-format names like order/paid and subscription/created. The Events list API may return internal eventType strings (for example s_order_paid) — these are for internal analytics and should not be used when creating webhooks.

Webhook signature verification (HMAC-SHA256)

TagadaPay signs the exact JSON string sent as the request body.

Read the raw body as a string (do not parse JSON before verifying).
Compute HMAC-SHA256(secret, rawBody) and hex-encode the digest.
Compare to the X-TagadaPay-Signature header value after the sha256= prefix.

import crypto from 'crypto';

function verifyTagadaWebhook(rawBody: string, secret: string, signatureHeader: string | null) {
  if (!signatureHeader?.startsWith('sha256=')) return false;
  const expected = signatureHeader.slice('sha256='.length);
  const hmac = crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(hmac, 'hex'));
  } catch {
    return false;
  }
}

Other headers on the request include X-TagadaPay-Timestamp and User-Agent: TagadaPay-Webhooks/1.0. You can use the timestamp for optional replay protection.

SDK methods reference

Resource	Method	Description
`webhooks`	`create(params)`	Create endpoint; params: `storeId`, `url`, `eventTypes`, optional `description`
`webhooks`	`list(storeId)`	List all webhooks for a store
`webhooks`	`del(id)`	Delete webhook; returns `{ success, id }`
`events`	`recent(limit?)`	Most recent events
`events`	`statistics(params?)`	Aggregates; optional `storeId`, `startDate`, `endDate`
`events`	`list(params?)`	Filtered list with `filters`, `pagination`, `sortBy`, `search`
`events`	`retrieve(eventId)`	Single event by id

Next steps

Node SDK Quick Start

Install the SDK, authenticate, and explore core resources

Sandbox Testing

Exercise payments and webhook-style flows without live processors

Merchant Quick Start

End-to-end store, funnel, and checkout setup

Subscriptions

Recurring billing and subscription lifecycle

Documentation Index

​Webhooks & Events

​What webhooks are (and why use them)

​Create a webhook

​The signing secret

​List webhooks

​Delete a webhook

​Available event types

​Order events

​Checkout events

​Payment events

​Subscription events

​Funnel events

​Club events

​Security events

​Events API (query & analytics)

​Recent events

​Statistics

​List with filters and pagination

​Webhook signature verification (HMAC-SHA256)

​SDK methods reference

​Next steps

Node SDK Quick Start

Sandbox Testing

Merchant Quick Start

Subscriptions

Webhooks & Events

What webhooks are (and why use them)

Create a webhook

The signing secret

List webhooks

Delete a webhook

Available event types

Order events

Checkout events

Payment events

Subscription events

Funnel events

Club events

Security events

Events API (query & analytics)

Recent events

Statistics

List with filters and pagination

Webhook signature verification (HMAC-SHA256)

SDK methods reference

Next steps