Webhook

Webhook Event

​

Sweuze sends webhook events to your configured endpoint when payment status changes occur. All events follow the same envelope structure with a type field that determines the event category.

Event Categories

Payment Intent Events - Lifecycle of a payment intent:

  • payment_intent.initiated - Intent created (first event)
  • payment_intent.requires_action - Customer action needed (redirect or display requisites)
  • payment_intent.processing - Provider is processing the payment
  • payment_intent.succeeded - Payment complete (fulfill order)
  • payment_intent.failed - Intent failed (e.g. provider error, customer rejection)
  • payment_intent.canceled - Payment canceled/expired

Payment Events - Transaction processing:

  • payment.pending - Pending confirmation
  • payment.processing - Provider processing
  • payment.succeeded - Payment captured
  • payment.failed - Payment failed

Webhook Security

All webhook requests include authentication via the X-Signature header:

Format: t=timestamp,v1=current_signature,v0=old_signature

Verification:

signed_payload = timestamp + "." + request_body
expected_sig = HMAC-SHA256(signed_payload, webhook_secret)

# Compare with v1 (constant-time comparison)
if expected_sig == v1: accept

# During rotation, also check v0
if expected_sig == v0: accept

# Validate timestamp (reject if > 5 minutes old)
if abs(now - timestamp) > 300: reject

See implementation examples in the guides.

Body·WebhookPayload
required
application/json
  • data
    required

    Event-specific data. Structure depends on the event type (discriminated by type).

    • type
      Discriminator
      Type: string
      required

      Event type

    • amount
      Type: string Pattern: ^\d+\.\d{8}$
      required

      Payment amount as a decimal string with eight decimal places

    • currency
      Type: string
      required

      Three-letter ISO 4217 currency code

    • customerId
      Type: string
      required

      Customer identifier from your system

    • id
      Type: stringFormat: uuid
      required

      Payment intent identifier

    • merchantId
      Type: stringFormat: uuid
      required

      Associated merchant ID

    • merchantReference
      Type: string
      required

      Your order/transaction reference

    • paymentMethodId
      Type: string
      required

      Payment method identifier

    • status
      Type: stringenum
      required

      Status of the payment intent. Matches the second segment of type (e.g. succeeded for payment_intent.succeeded).

      values
      • initiated
      • requires_action
      • processing
      • succeeded
      • failed
      • canceled
    • action
      nullable
    • paymentId
      Type: stringFormat: uuid nullable

      Associated payment ID (null until payment is created)

  • id
    Type: stringFormat: uuid
    required

    Unique webhook notification identifier (use for idempotency)

  • occurredAt
    Type: stringFormat: date-time
    required

    ISO 8601 timestamp with milliseconds when the event occurred

  • type
    Type: stringenum
    required

    Event type that determines the structure of the data field

    values
    • payment_intent.initiated
    • payment_intent.requires_action
    • payment_intent.processing
    • payment_intent.succeeded
    • payment_intent.canceled
  • version
    Type: string
    required

    API version used for this webhook payload

Responses
  • 200

    Webhook received successfully

  • 202

    Webhook accepted for processing

Request Example for postwebhook_event
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "payment_intent.succeeded",
  "version": "2026.1.0",
  "occurredAt": "2025-11-18T15:30:00.000+00:00",
  "data": {
    "type": "payment_intent.succeeded",
    "id": "948688ed-451f-49e3-8084-b23f3ee32aa2",
    "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "merchantId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "merchantReference": "ORDER-12345",
    "paymentMethodId": "mbway-eupago",
    "customerId": "cust_abc123",
    "amount": "50.00000000",
    "currency": "EUR",
    "status": "succeeded",
    "action": null
  }
}
No Body

Webhook received successfully