Webhooks

Payment providers send webhooks to notify about async payment events (Multibanco payments, 3DS completions, refunds). The checkout app receives these webhooks and forwards them to the Commerce API for order reconciliation.

Webhook routesCopy Anchor Link

POST /api/webhooks/{provider}/{org}
GET  /api/webhooks/{provider}/{org}  (provider verification)

Example URLsCopy Anchor Link

POST https://checkout.example.com/api/webhooks/stripe/org_abc123
POST https://checkout.example.com/api/webhooks/easypay/org_abc123
POST https://checkout.example.com/api/webhooks/ifthenpay/org_abc123

FlowCopy Anchor Link

Per-tenant verificationCopy Anchor Link

Each store connects its own provider in the dashboard (Integrations page). The verification flow:

1. Load the store's integration_config for the provider
2. Decrypt its credentials
3. Verify the call with provider.verifyWebhook()

What that means depends on the provider. Stripe checks the signature against the store's webhookSecret. Ifthenpay checks the anti-phishing key. Easypay notifications are unsigned, so the body is only a trigger: the payment is read back from Easypay's API, and that response is the source of truth.

There is no environment fallback.

// @prood/commerce
export async function verifyPaymentWebhook(tenantId, providerId, payload, signature) {
  const { provider } = await getTenantPaymentProvider(tenantId, providerId, { includeDisabled: true })
  return provider.verifyWebhook(payload, signature)
}

Provider-specific setupCopy Anchor Link

StripeCopy Anchor Link

1. In Stripe Dashboard → Webhooks → Add endpoint
2. URL: https://checkout.example.com/api/webhooks/stripe/{orgId}
3. Events: checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, checkout.session.expired, charge.refunded
4. Copy signing secret → dashboard Integrations → Stripe → webhook secret

Or run ./scripts/stripe-webhook-setup.sh to configure via CLI.

EasypayCopy Anchor Link

1. Configure webhook URL in Easypay merchant panel
2. URL: https://checkout.example.com/api/webhooks/easypay/{orgId}
3. Easypay sends payment status notifications

IfthenpayCopy Anchor Link

1. Configure callback URL in Ifthenpay backoffice
2. URL: https://checkout.example.com/api/webhooks/ifthenpay/{orgId}
3. Anti-phishing key used for verification

Webhook as safety netCopy Anchor Link

Webhooks complement the sync-on-return flow:

The checkout state machine's handleWebhookUpdate() can transition from any non-terminal state based on webhook data.

API webhook endpointCopy Anchor Link

The Commerce API also exposes a direct webhook endpoint:

POST /v1/webhooks/payments/{provider}?org={orgId}
Header: x-checkout-secret: {CHECKOUT_API_SECRET}

This is the target of forwardPaymentWebhook(). It can also be called directly if webhooks are routed to the API domain instead of the checkout domain.

Related pagesCopy Anchor Link