SupportLog in
DocsAPI ReferenceSDK ReferenceResourcesChangelog
Hybrid

Dual Webhooks

Why a hybrid integration receives two webhook formats, and how to handle both on one endpoint.

In the Hybrid model, a single transaction can emit two webhooks: one in Long format (from Hosted/SDK, for the card) and one in Short format (from API Direct, for non-card methods, withdrawals, and refunds). This is by design.

Why duplicate webhooks arrive

Because each leg of your integration (SDK/Hosted for cards, API Direct for everything else) has its own webhook channel, you'll receive notifications from both. A single payment can generate a Pending event and then a Success for each channel involved.

Duplicate webhooks in Hybrid mode are intentional (Pending + Success). Always implement deduplication using metadata.external_id on your side.

What you need to configure

  • Two webhook endpoints, one per integration style.
  • Separate handling logic: Hosted/SDK-style webhooks for card transactions, and API Direct-style for other methods, withdrawals, and refunds.

Deduplication checklist

  • Dedupe on metadata.external_id (works across Short + Long formats).
  • Keep an idempotency_key index in your DB.
  • Treat duplicate Pending + Success in Hybrid mode as intentional.
  • Always verify final status via GET /api/v1/transactions/{id}/.
  • Handle Declined for withdrawals as a terminal state.

Next steps

Webhooks model

Short vs Long formats in depth.

Hybrid reference

Format and correlation key per leg.

Correlation keys

Reconcile with metadata.external_id.

Was this page helpful?

Overview & When to Use It

Combine SDK or Hosted for cards with API Direct for APMs and payouts, without PCI scope.

Reference

Which leg covers each capability in a hybrid integration, plus the refund and payout rules.

On this page

Why duplicate webhooks arriveWhat you need to configureDeduplication checklistNext steps