​
Webhook event reference

​
Checkout

  • checkout.created: A checkout session was created.
  • checkout.paid: The customer completed payment.
  • checkout.expired: The checkout expired without payment.
{
  "type": "checkout.created",
  "createdAt": "2025-01-15T10:00:00Z",
  "data": {
    "checkoutId": "cs_abc123",
    "customerId": "cus_abc123",
    "mode": "payment"
  }
}

{
  "type": "checkout.paid",
  "createdAt": "2025-01-15T10:04:23Z",
  "data": {
    "checkoutId": "cs_abc123",
    "customerId": "cus_abc123",
    "productId": "prod_abc123"
  }
}

{
  "type": "checkout.expired",
  "createdAt": "2025-01-15T11:00:00Z",
  "data": {
    "checkoutId": "cs_abc123",
    "customerId": "cus_abc123",
    "mode": "payment"
  }
}

​
Invoices

  • invoice.created: An invoice was generated.
  • invoice.paid: An invoice was paid.
  • invoice.failed: Invoice payment failed.
{
  "type": "invoice.created",
  "createdAt": "2025-01-15T10:00:00Z",
  "data": {
    "invoiceId": "inv_abc123",
    "customerId": "cus_abc123",
    "subscriptionId": "sub_abc123"
  }
}

{
  "type": "invoice.paid",
  "createdAt": "2025-01-15T10:04:23Z",
  "data": {
    "invoiceId": "inv_abc123",
    "customerId": "cus_abc123",
    "subscriptionId": "sub_abc123"
  }
}

{
  "type": "invoice.failed",
  "createdAt": "2025-01-15T10:04:23Z",
  "data": {
    "invoiceId": "inv_abc123",
    "customerId": "cus_abc123",
    "subscriptionId": "sub_abc123"
  }
}

​
Subscriptions

  • subscription.created: A subscription was created.
  • subscription.active: The first payment was received.
  • subscription.renewed: The subscription renewed for another period.
  • subscription.past_due: A renewal payment failed.
  • subscription.canceled: The subscription was canceled.
{
  "type": "subscription.created",
  "createdAt": "2025-01-15T10:00:00Z",
  "data": {
    "subscriptionId": "sub_abc123",
    "customerId": "cus_abc123",
    "status": "trialing"
  }
}

{
  "type": "subscription.active",
  "createdAt": "2025-01-15T10:04:23Z",
  "data": {
    "subscriptionId": "sub_abc123",
    "customerId": "cus_abc123"
  }
}

{
  "type": "subscription.renewed",
  "createdAt": "2025-02-15T10:04:23Z",
  "data": {
    "subscriptionId": "sub_abc123",
    "customerId": "cus_abc123",
    "invoiceId": "inv_def456"
  }
}

{
  "type": "subscription.past_due",
  "createdAt": "2025-02-15T10:04:23Z",
  "data": {
    "subscriptionId": "sub_abc123",
    "customerId": "cus_abc123"
  }
}

{
  "type": "subscription.canceled",
  "createdAt": "2025-02-20T10:04:23Z",
  "data": {
    "subscriptionId": "sub_abc123",
    "customerId": "cus_abc123"
  }
}

​
Transactions

  • transaction.pending: A payment was initiated.
  • transaction.completed: A payment was confirmed.
  • transaction.failed: A payment failed.
  • transaction.refunded: A payment was refunded.
{
  "type": "transaction.pending",
  "createdAt": "2025-01-15T10:00:00Z",
  "data": {
    "transactionId": "tx_abc123",
    "checkoutId": "cs_abc123",
    "amount": "9700",
    "currency": "BRL"
  }
}

{
  "type": "transaction.completed",
  "createdAt": "2025-01-15T10:04:23Z",
  "data": {
    "transactionId": "tx_abc123",
    "checkoutId": "cs_abc123",
    "amount": "9700",
    "currency": "BRL"
  }
}

{
  "type": "transaction.failed",
  "createdAt": "2025-01-15T10:04:23Z",
  "data": {
    "transactionId": "tx_abc123",
    "checkoutId": "cs_abc123",
    "amount": "9700",
    "currency": "BRL"
  }
}

{
  "type": "transaction.refunded",
  "createdAt": "2025-01-15T10:10:00Z",
  "data": {
    "transactionId": "tx_abc123",
    "amount": "9700",
    "currency": "BRL"
  }
}

​
Usage

  • usage.recorded: A usage event was recorded.
  • usage.blocked: Usage was blocked because the customer has no access.
{
  "type": "usage.recorded",
  "createdAt": "2025-01-15T10:00:00Z",
  "data": {
    "customerId": "cus_abc123",
    "meterId": "meter_abc123",
    "quantity": 1
  }
}

{
  "type": "usage.blocked",
  "createdAt": "2025-01-15T10:00:00Z",
  "data": {
    "customerId": "cus_abc123",
    "meterId": "meter_abc123",
    "reason": "insufficient_credits"
  }
}

​
Credits

  • credits.added: Credits were added to a customer.
  • credits.debited: Credits were deducted.
  • credits.depleted: The customer reached zero balance.
{
  "type": "credits.added",
  "createdAt": "2025-01-15T10:00:00Z",
  "data": {
    "customerId": "cus_abc123",
    "amount": "5000",
    "currency": "USDC"
  }
}

{
  "type": "credits.debited",
  "createdAt": "2025-01-15T10:05:00Z",
  "data": {
    "customerId": "cus_abc123",
    "amount": "100",
    "currency": "USDC"
  }
}

{
  "type": "credits.depleted",
  "createdAt": "2025-01-15T10:10:00Z",
  "data": {
    "customerId": "cus_abc123",
    "currency": "USDC"
  }
}

​
Entitlements

  • entitlement.active: The customer gained access.
  • entitlement.revoked: Access was revoked.
  • entitlement.expired: Access expired.
{
  "type": "entitlement.active",
  "createdAt": "2025-01-15T10:04:23Z",
  "data": {
    "customerId": "cus_abc123",
    "productId": "prod_abc123"
  }
}

{
  "type": "entitlement.revoked",
  "createdAt": "2025-01-20T10:04:23Z",
  "data": {
    "customerId": "cus_abc123",
    "productId": "prod_abc123"
  }
}

{
  "type": "entitlement.expired",
  "createdAt": "2025-02-15T10:04:23Z",
  "data": {
    "customerId": "cus_abc123",
    "productId": "prod_abc123"
  }
}

​
Payouts

  • payout.created: A payout request was received.
  • payout.completed: A payout was sent successfully.
  • payout.failed: A payout failed.
{
  "type": "payout.created",
  "createdAt": "2025-01-15T10:00:00Z",
  "data": {
    "payoutId": "pay_abc123",
    "amount": "5000000",
    "currency": "USDC"
  }
}

{
  "type": "payout.completed",
  "createdAt": "2025-01-15T10:02:00Z",
  "data": {
    "payoutId": "pay_abc123",
    "amount": "5000000",
    "currency": "USDC",
    "txHash": "0xabc123"
  }
}

{
  "type": "payout.failed",
  "createdAt": "2025-01-15T10:02:00Z",
  "data": {
    "payoutId": "pay_abc123",
    "amount": "5000000",
    "currency": "USDC",
    "reason": "insufficient_balance"
  }
}