Webhooks

TagadaPay pushes processing events to your HTTPS endpoint as they happen: a charge fails, a payout lands, a dispute opens. One partner-level endpoint receives events for all your TPAs — the account field on every event tells you which merchant it belongs to (Stripe Connect semantics). Direct merchants subscribe per-TPA the same way. Requires @tagadapay/node-sdk ≥ 3.8.0.

1. Create an endpoint

const endpoint = await tagada.partners.processing.webhookEndpoints.create({
  url: 'https://example.com/webhooks/tagada',
  enabledEvents: ['payout.*', 'dispute.*', 'charge.failed', 'chargeback_alert.*'],
});

// ⚠️ Store this — it signs every delivery to this endpoint.
console.log(endpoint.secret); // whsec_…

With a partner key the endpoint is created at partner scope automatically (events for all your TPAs). With a TPA-pinned merchant key it is scoped to that TPA. enabledEvents accepts exact types (payout.paid), prefixes (payout.*), or '*' for everything. Manage endpoints with list(), retrieve(id), update(id, { url, enabledEvents, status }) and del(id). Set status: 'disabled' to pause deliveries instantly.

2. Verify and handle events

Every delivery is signed with your endpoint’s whsec_… secret (header tagadapay-signature, Stripe-style t=<unix>,v1=<hmac>). Use the SDK helper — it verifies and parses in one call, and throws on a bad signature:

import express from 'express';
import { constructProcessingEvent } from '@tagadapay/node-sdk';

const app = express();

app.post('/webhooks/tagada', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = constructProcessingEvent(
      req.body.toString('utf8'),          // MUST be the raw body
      req.headers['tagadapay-signature'] as string,
      process.env.TAGADA_WEBHOOK_SECRET!, // the endpoint's whsec_…
    );
  } catch {
    return res.sendStatus(400);
  }

  switch (event.type) {
    case 'payout.paid':
      console.log(`Payout paid for ${event.account}:`, event.data.object);
      break;
    case 'dispute.created':
      notifyMerchant(event.account, event.data.object);
      break;
  }

  res.sendStatus(200); // respond 2xx fast; do heavy work async
});

The event envelope:

{
  "id": "evt_9f2c41d3a8b7e6f01c2d3e4f",
  "object": "event",
  "type": "payout.paid",
  "account": "tpa_1f770ea2c614",
  "mode": "live",
  "created": "2026-07-15T17:40:12.000Z",
  "data": {
    "object": {
      "object": "payout",
      "id": "po_8823…",
      "amountMinor": 125000,
      "currency": "EUR",
      "status": "paid",
      "bankAccountLast4": "1234"
    }
  }
}

Event ids are deterministic — if a payment processor redelivers the same underlying webhook to us, you will not receive it twice. Still design handlers to be idempotent on event.id.

Event types

Family	Types
Charges	`charge.authorized`, `charge.succeeded`, `charge.failed`, `charge.voided`, `charge.refunded`
Refunds	`refund.succeeded`, `refund.failed`
Disputes	`dispute.created`, `dispute.updated`, `dispute.closed`
Payouts	`payout.created`, `payout.paid`, `payout.failed`, `payout.canceled`
Chargeback alerts	`chargeback_alert.created`, `chargeback_alert.refunded`
Onboarding	`account.application.submitted`, `account.application.approved`, `account.application.declined`
KYC	`account.kyc.requested`, `account.kyc.approved`, `account.kyc.rejected`
Documents	`document.requested`, `document.uploaded`, `document.verified`, `document.rejected`
Contracts	`account.contract.sent`, `account.contract.signed`, `account.contract.declined`
Account status	`account.activated`, `account.suspended`, `account.payments_enabled`, `account.payouts_enabled`
Requirements	`account.requirements.updated`
Gateway protection	`account.gwp.completed`

This table is the whole catalog — there is nothing else to subscribe to. An enabledEvents entry that names anything outside it is rejected with 400 invalid_body listing the offenders, so a typo fails at subscription time rather than by silently never delivering. Subscribing to a family is easier than listing names: account.* and document.* cover the onboarding lifecycle and pick up events added later. Nested prefixes such as account.kyc.* work too.

Onboarding events reach partner-owned endpoints regardless of the merchant’s own notification preferences. Those preferences govern the merchant’s in-app and email notifications only; they no longer gate webhook delivery.

charge.* payloads include a card block with PSP-agnostic BIN intelligence (funding credit/debit, segment consumer/business/commercial/government, isCommercial, prepaid, issuer country/name/currency, card product) resolved from Tagada’s own enrichment data — ready for commercial-card surcharging and risk rules without any acquirer-specific configuration. See Card intelligence.

Payload by family

data.object depends on the event family. Every object carries an object discriminator, so branch on data.object.object rather than on the event name when one type can arrive in more than one shape. Onboarding, KYC, contracts, account status (account.application.approved / .declined, account.kyc.*, account.contract.*, account.activated, account.suspended, account.payments_enabled, account.payouts_enabled):

{
  "object": "notification",
  "id": "d312bc21-c642-4fb1-a276-b4dd1cbe596f",
  "type": "account.contract.signed",
  "title": "Contract signed",
  "body": "The merchant agreement for Acme Ltd has been signed.",
  "priority": "normal",
  "createdAt": "2026-08-27T17:31:04.000Z"
}

title and body are the merchant-facing wording, not structured fields. Treat these events as a signal and read the merchant’s current state from GET /v1/partner/tpas/{id} for the details (contract, KYC outcome, enabled capabilities). Application submitted (account.application.submitted):

{ "object": "application", "id": "ent_d70b39cdf84e46269dfc3921ec3f2455", "status": "submitted" }

Documents (document.requested, document.uploaded, document.verified, document.rejected):

{
  "object": "document",
  "id": "dreq_de5843c1fb417799243a08ce",
  "documentType": "Bank statement (in the company's legal name)",
  "status": "open",
  "provider": "sumsub",
  "reason": null
}

id is dreq_… for a request raised on the payfac account and edreq_… for one raised on the application; documentType is the label shown to the merchant, not an enum. status is the request’s own state (open for a new request, then uploaded, verified, rejected); reason carries the reviewer’s note on a rejection. document.requested can also arrive with the notification shape above when the request was raised through the merchant notification flow, hence the advice to branch on data.object.object. Requirements (account.requirements.updated, one event per change to the checklist):

{
  "object": "account_requirements",
  "currentlyDue": ["banking.account_number", "representative.id_number"],
  "pastDue": [],
  "pendingVerification": ["business.registration_number"],
  "outstandingCount": 2
}

Gateway protection (account.gwp.completed):

{ "object": "gwp", "id": "ck_req_4ht4WzZLew", "status": "live", "completedAt": "2026-08-26T09:12:40.000Z" }

Charges, refunds, disputes, chargeback alerts, payouts carry the corresponding processing object (charge, refund, dispute, chargeback_alert, payout) with the same fields as the reporting API; see the payout example above and Reporting.

Retries

A delivery that doesn’t get a 2xx within 10 seconds is retried with backoff 1 min → 10 min → 1 h → 6 h → 24 h (6 attempts total), then marked failed. Failures never block other events.

3. Delivery log & replay

Audit exactly what was sent, when, and what your server answered:

const { data: deliveries } = await tagada.partners.processing.webhookEndpoints.deliveries.list(
  endpoint.id,
  { status: 'failed', limit: 50 },
);

for (const d of deliveries) {
  console.log(d.eventType, d.status, d.statusCode, d.attempt, d.error);
}

// Missed something during an outage? Re-send the exact original payload:
await tagada.partners.processing.webhookEndpoints.deliveries.replay(endpoint.id, deliveries[0].id);

Replays create a fresh delivery (the historical row is preserved) with the exact original payload — same event.id, so idempotent consumers stay safe.

Testing your integration

Point a temporary endpoint at a request inspector (e.g. https://webhook.site/…), subscribe to '*', then trigger a test event — the fastest is an on-demand payout or a small refund on a test TPA. Check the delivery log to confirm the 200.

Get Started

CRM provisioning

Processing provisioning

REST reference

Server-to-server payments

Money movement

Reporting & disputes

End-to-end

Webhooks

Webhooks

1. Create an endpoint

2. Verify and handle events

Event types

Payload by family

Retries

3. Delivery log & replay

Testing your integration

​Webhooks

​1. Create an endpoint

​2. Verify and handle events

​Event types

​Payload by family

​Retries

​3. Delivery log & replay

​Testing your integration

Webhooks

1. Create an endpoint

2. Verify and handle events

Event types

Payload by family

Retries

3. Delivery log & replay

Testing your integration