Skip to main content

​
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 TagadaPay dispatches (see the table below). If a string does not match a fired event, no delivery occurs for that subscription.

​
List webhooks

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

​
Delete a webhook

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

​
Common event types

These are representative types you can subscribe to. The platform may emit additional types over time; use events.list or events.recent to see what your account is actually recording.
Event typeTypical use
order.createdOrder record created (confirm in your tenant — paid checkout often surfaces as order.paid)
order.paidOrder successfully paid; trigger fulfillment or CRM updates
payment.completedCrypto / alternative payment flows marking completion
payment.expiredPayment window expired without completion
subscription.createdNew subscription started
subscription.canceledSubscription canceled (US spelling in API)
subscription.rebill_upcomingUpcoming rebill notification
subscription.updatedPlan or status changed
subscription.paused / subscription.resumedPause lifecycle
subscription.rebillSuccessful rebill charge (renewal)
subscription.renewedSome integrations use this name; TagadaPay may emit subscription.rebill instead — verify in events.recent
refund.createdRefund initiated or recorded
Some docs or examples may use aliases like order.created or subscription.cancelled. Always use the exact string your environment dispatches. When in doubt, inspect eventType on records returned by events.recent or events.list.

​
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 dispatch names like order.paid and subscription.created. Events list responses may use different internal eventType strings (for example s_order_paid). Inspect events.recent() or a sample events.list() response to see the exact values for your account.

​
Webhook signature verification (HMAC-SHA256)

TagadaPay signs the exact JSON string sent as the request body.
  1. Read the raw body as a string (do not parse JSON before verifying).
  2. Compute HMAC-SHA256(secret, rawBody) and hex-encode the digest.
  3. 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

ResourceMethodDescription
webhookscreate(params)Create endpoint; params: storeId, url, eventTypes, optional description
webhookslist(storeId)List all webhooks for a store
webhooksdel(id)Delete webhook; returns { success, id }
eventsrecent(limit?)Most recent events
eventsstatistics(params?)Aggregates; optional storeId, startDate, endDate
eventslist(params?)Filtered list with filters, pagination, sortBy, search
eventsretrieve(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