Event

The Event object represents a webhook notification about activity in your Fungies store.

Events are notifications that inform you when something significant happens in your Fungies account. When an event occurs - such as a successful Payment or Subscription cancellation - we create an Event object and send it to your configured webhook endpoints.

You can use events to trigger workflows in your application, such as fulfilling Orders, sending custom emails, or syncing data with your backend systems.

Event delivery

Events are delivered to your webhook endpoints via HTTP POST requests. Each event includes:

  • A unique id for deduplication
  • An idempotencyKey to prevent duplicate processing
  • The event type indicating what happened
  • A data payload with relevant objects

Events may be delivered more than once. Use the idempotencyKey to ensure you process each event only once.

Event types

These are the event types currently supported. We may add more at any time, so your code should handle unknown event types gracefully.

Event TypeDescription
payment_successA Payment has been successfully processed. Use this to fulfill orders and grant subscription access.
payment_refundedA Payment has been refunded (full or partial)
payment_failedA Payment attempt has failed
subscription_createdA new Subscription record exists in Stripe/Fungies. May include PENDING payment data if sent before checkout finishes — not a paid signal by itself.
subscription_intervalA Subscription's billing interval has been charged
subscription_updatedA Subscription has been modified
subscription_cancelledA Subscription has been cancelled

Subscription signup events

On the first subscription checkout, Fungies sends both events when your webhook is subscribed to both types. They are produced by different Stripe notifications and may arrive seconds apart or out of order.

  • subscription_created — subscription object created; data.lastPayment may still be PENDING and data.subscription.status incomplete. There is no data.order on this event.
  • payment_success — initial subscription_initial payment is PAID; safe to fulfill.

Treat subscription_created as informational (lifecycle, CRM, analytics). Treat payment_success as the fulfillment trigger for the first charge.

The Event object

idstringrequired

Unique identifier (UUID) for this event. It carries no prefix.

typestringrequired

The type of event that occurred. See Event types above.

idempotencyKeystringrequired

Unique key (UUID) for idempotent event processing. Use this to prevent duplicate handling of the same event. It is always equal to id — deduplicating on either one is the same thing.

testModebooleanrequired

Whether this event occurred in test mode (true) or live mode (false).

dataobjectrequired

The event payload containing related objects. Its shape depends on the event family — see Payload shape by event below. Do not assume a key is present without checking the table.

Payload shape by event

data carries different keys for payment events and subscription events. The most common mistake is reading data.order or data.payment on a subscription event: neither exists there.

KeyPayment events
payment_success, payment_failed, payment_refunded		Subscription events
subscription_created, subscription_updated, subscription_interval, subscription_cancelled
items✅ always✅ always
user✅ always✅ always
customer✅ always (alias of user, kept for compatibility)❌ absent
order✅ always❌ absent
payment✅ always❌ absent
lastPayment❌ absent✅ always — the most recent payment for the subscription
subscriptionOnly when the payment belongs to a subscription✅ always
refundOnly on payment_refunded❌ absent

On payment events, data.customer and data.user are the same User object. Prefer data.user — it is the one key present on every event.

data.itemsarray

Array of line items involved in the transaction. See Item object below.

data.userUser

The User object representing the customer.

data.orderOrder

The Order object associated with this event. Payment events only.

data.paymentPayment

The Payment object for the transaction. Payment events only.

data.lastPaymentPayment

The most recent Payment object for the subscription. Subscription events only — on subscription_created it can still be PENDING.

data.subscriptionSubscription

The Subscription object. Always present on subscription events; on payment events, present only when that payment belongs to a subscription.

data.refundRefund

The refund this event is about. Present on payment_refunded only — see Refund object below.

Refund object

data.refund describes the single refund that triggered a payment_refunded event. An order can be refunded more than once: each refund sends its own event, and cumulativeAmountRefunded is the running total across all of them — use it rather than adding up amounts, because events can arrive out of order or be redelivered.

This object was added to payment_refunded after the event type first shipped. If your handler needs it, treat it as optional until you have confirmed your integration receives it.

objectstring

Object type identifier. Always "refund".

idstringrequired

The payment provider's own identifier for this refund. Use it to reconcile against your provider records and to deduplicate repeat deliveries of the same refund.

statusstringrequired

One of pending, succeeded, failed, canceled, requires_action. A refund can be reported before the bank settles it, so pending is a normal first state.

amountintegerrequired

Amount refunded by THIS refund, in the currency's minor units (e.g. 1050 = 10.50). Tax included.

currencystring

Three-letter currency code, matching the order's currency.

cumulativeAmountRefundedintegerrequired

Total refunded on the order so far, this refund included, in minor units. Compare it against the order total to tell a partial refund from a full one.

reasonstring

Why the refund was issued, when one was given.

createdAtinteger

Unix timestamp in milliseconds for when the refund was created.

Item object

Each item in the data.items array represents a line item in the Order.

objectstring

Object type identifier. Always "item".

idstringrequired

Unique identifier (UUID) for this line item.

namestringrequired

Display name of the item.

valueintegerrequired

Item price in the smallest currency unit. Defaults to 0.

quantityintegerrequired

Number of units purchased.

currencystringrequired

Three-letter ISO 4217 currency code.

productobjectrequired

The Product this item belongs to, in short form — object, id (UUID), type, and internalId. Not the full Product object: there is no name here, so read the item's own name for display.

offerobjectrequired

The Offer purchased, in short form — object, id (UUID), and internalId. Always present.

variantobject | null

The product variant, in short form — object, id (UUID), and internalId. null when the offer has no variant.

planobject | null

For a Subscription offer, the same variant object repeated under a subscription-friendly name (variants are used as plans). null for one-time offers.

customFieldsobject | null

Key-value pairs of custom fields defined by you and filled by the customer during checkout. Only keys that exactly match a field's Key (configured in the Dashboard) are included — an unmatched or undefined key is silently omitted rather than sent as an empty value.

Example event payload

Payment event

{
  "id": "770e8400-e29b-41d4-a716-446655440010",
  "type": "payment_success",
  "idempotencyKey": "770e8400-e29b-41d4-a716-446655440010",
  "testMode": false,
  "data": {
    "items": [
      {
        "object": "item",
        "id": "cc0e8400-e29b-41d4-a716-446655440020",
        "name": "Pro Plan - Monthly",
        "value": 2999,
        "quantity": 1,
        "currency": "USD",
        "product": {
          "object": "product",
          "id": "bb0e8400-e29b-41d4-a716-446655440006",
          "type": "Subscription",
          "internalId": "prod_pro"
        },
        "offer": {
          "object": "offer",
          "id": "aa0e8400-e29b-41d4-a716-446655440005",
          "internalId": "plan_pro_monthly"
        },
        "variant": {
          "object": "variant",
          "id": "dd0e8400-e29b-41d4-a716-446655440030",
          "internalId": "var_monthly"
        },
        "plan": {
          "object": "variant",
          "id": "dd0e8400-e29b-41d4-a716-446655440030",
          "internalId": "var_monthly"
        },
        "customFields": {
          "license_type": "single"
        }
      }
    ],
    "order": {
      "object": "order",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "number": "L8VQK3N2M7KpQ9nR",
      "status": "PAID",
      "value": 2999,
      "currency": "USD"
    },
    "payment": {
      "object": "payment",
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "number": "L8VQK3N2M7KpQ9nR",
      "status": "PAID"
    },
    "user": {
      "object": "user",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "customer@example.com",
      "username": null,
      "internalId": "usr_abc123"
    },
    "customer": {
      "object": "user",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "customer@example.com",
      "username": null,
      "internalId": "usr_abc123"
    }
  }
}

Subscription event

Note what is missing: no order, no payment, no customer.

{
  "id": "770e8400-e29b-41d4-a716-446655440011",
  "type": "subscription_interval",
  "idempotencyKey": "770e8400-e29b-41d4-a716-446655440011",
  "testMode": false,
  "data": {
    "items": [
      {
        "object": "item",
        "id": "cc0e8400-e29b-41d4-a716-446655440020",
        "name": "Pro Plan - Monthly",
        "value": 2999,
        "quantity": 1,
        "currency": "USD",
        "product": {
          "object": "product",
          "id": "bb0e8400-e29b-41d4-a716-446655440006",
          "type": "Subscription",
          "internalId": "prod_pro"
        },
        "offer": {
          "object": "offer",
          "id": "aa0e8400-e29b-41d4-a716-446655440005",
          "internalId": "plan_pro_monthly"
        },
        "variant": {
          "object": "variant",
          "id": "dd0e8400-e29b-41d4-a716-446655440030",
          "internalId": "var_monthly"
        },
        "plan": {
          "object": "variant",
          "id": "dd0e8400-e29b-41d4-a716-446655440030",
          "internalId": "var_monthly"
        },
        "customFields": {}
      }
    ],
    "user": {
      "object": "user",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "customer@example.com",
      "username": null,
      "internalId": "usr_abc123"
    },
    "subscription": {
      "object": "subscription",
      "id": "L8VQK3N2M7KpQ9nR",
      "status": "active"
    },
    "lastPayment": {
      "object": "payment",
      "id": "660e8400-e29b-41d4-a716-446655440004",
      "number": "L8VQK3N2M7KpQ9nR-0003",
      "status": "PAID"
    }
  }
}

subscription and lastPayment are the full Subscription and Payment objects; the examples above are abridged.

Webhooks Setup

Configure webhook endpoints

Webhooks Overview

Learn about webhooks

Orders

Order object reference

Payments

Payment object reference

Last updated

Webhook

The Webhook object represents an endpoint configured to receive Event notifications.