Payment Events

Available webhook events and their payloads for payment processing

Event Strucure

All webhook events follow this structure:

interface WebhookEvent<T> {
  meta: {
    occured_at: string; // ISO 8601 timestamp when event occurred
    event_type: string; // Event type (e.g., "subscription.created")
    event_id: string; // Unique event identifier (format: zelwhk_timestamp_random)
  };
  data: T; // Event-specific payload
}

Event Payloads

All payment events use the same normalized payload structure regardless of payment provider:

Subscription Events

// subscription.created or subscription.updated
{
  "meta": {
    "occured_at": "2024-01-01T12:00:00.000Z",
    "event_type": "subscription.created",
    "event_id": "zelwhk_abc123_def456"
  },
  "data": {
    "id": 123,
    "collectionMode": "automatic",
    "email": "[email protected]", 
    "organizationId": "org_abc123",
    "canceledAt": null,
    "nextBilledAt": "2024-02-01T12:00:00.000Z",
    "pausedAt": null,
    "status": "active",
    "externalId": "sub_paddle123",
    "externalCustomerId": "cus_paddle456",
    "items": [
      {
        "productId": 1,
        "unitPrice": 2999,
        "currency": "USD",
        "planName": "Pro Plan",
        "externalPriceId": "pri_abc123",
        "externalProductId": "pro_def456",
        "quantity": 1
      }
    ],
    "customer": {
      "id": "cus_internal_789",
      "externalId": "cus_paddle456", 
      "email": "[email protected]"
    }
  }
}

Transaction Events

// transaction.created or transaction.updated
{
  "meta": {
    "occured_at": "2024-01-01T12:00:00.000Z",
    "event_type": "transaction.created",
    "event_id": "zelwhk_xyz789_ghi012"
  },
  "data": {
    "id": 456,
    "billedAt": "2024-01-01T12:00:00.000Z",
    "externalId": "txn_paddle789",
    "subscriptionId": 123,
    "trackingSessionId": "sess_abc123",
    "productPriceAmount": 2999,
    "revisedAt": "2024-01-01T12:00:00.000Z",
    "status": "paid",
    "paymentMethodType": "card",
    "paymentMethodDetails": {
      "brand": "visa",
      "last4": "4242"
    },
    "totalAmountPaid": 2999,
    "paidCurrency": "USD",
    "totalAmount": 2999,
    "baseCurrency": "USD",
    "paymentProvider": "paddle",
    "customer": {
      "id": "cus_internal_789",
      "externalId": "cus_paddle456",
      "email": "[email protected]"
    }
  }
}

Available Event Types

Here are all the events you can receive (same for both Paddle and Stripe):

Event Type	Description
subscription.created	New subscription created
subscription.updated	Subscription details changed
transaction.created	New transaction recorded
transaction.updated	Transaction status changed

Event Delivery

Retry Policy

If your endpoint fails to respond with a 2xx status code, we'll retry with exponential backoff: - 1st retry: 5 minutes - 2nd retry: 30 minutes - 3rd retry: 2 hours - 4th retry: 5 hours - 5th retry: 10 hours

Event Ordering

While events are generally delivered in order, you should: - Use event timestamps for ordering - Handle out-of-order events gracefully - Implement idempotency checks