Webhooks Overview

Purpose

Webhooks provide real-time payment status notifications to your endpoint.

Configure at portal-test.sweuze.com → Developer → Webhooks.

Payload Structure

All webhooks follow this envelope:

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "payment_intent.succeeded",
  "version": "2025.1.0",
  "occurredAt": "2025-11-18T14:30:00.000+00:00",
  "data": {
    // Event-specific data (shape depends on `type`)
  }
}

Fields:

id: Webhook notification UUID (use for idempotency)
type: Event type (determines data structure)
version: API version of the webhook payload
occurredAt: ISO 8601 timestamp with milliseconds
data: Event-specific payload (always contains merchantId)

Event Categories

Payment Intent Events (payment_intent.*) - data is a PaymentIntentEventData:

data.id identifies the payment intent
data.paymentId identifies the associated payment (null until a payment is created)
data.merchantId identifies your merchant account
data.merchantReference matches the order reference you sent on POST /payment-intents
data.paymentMethodId, data.customerId, data.amount, data.currency, data.status
data.action is only populated on payment_intent.requires_action

Payment Events (payment.*) - data is a PaymentEventData:

data.id identifies the payment
data.paymentIntentId points back to the intent
data.merchantId, data.merchantReference, data.providerReference
data.paymentMethodId, data.customerId, data.amount, data.currency, data.status
data.errors[] is populated on payment.failed and empty otherwise

Amounts in webhook data are fixed-precision decimal strings with eight decimal places (e.g. "50.00000000"), while amounts in the REST API use two decimal places ("50.00").

See Event Types for the complete list with examples.

Security

Webhooks are signed with versioned signatures:

X-Signature: t=timestamp,v1=current_sig,v0=old_sig

See Signature Validation for implementation.

Open Banking (Rillpay)

Event Types