Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fungies.io/llms.txt

Use this file to discover all available pages before exploring further.

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 and data.order may still be PENDING.
  • 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

​
id
string
required
Unique identifier (UUID) for this event.
​
type
string
required
The type of event that occurred. See Event types above.
​
idempotencyKey
string
required
Unique key (UUID) for idempotent event processing. Use this to prevent duplicate handling of the same event.
​
testMode
boolean
required
Whether this event occurred in test mode (true) or live mode (false).
​
data
object
required
The event payload containing related objects.

​
Item object

Each item in the data.items array represents a line item in the Order.
​
object
string
Object type identifier. Always "item".
​
id
string
required
Unique identifier (UUID) for this line item.
​
name
string
required
Display name of the item.
​
value
integer
required
Item price in the smallest currency unit. Defaults to 0.
​
quantity
integer
required
Number of units purchased.
​
currency
string
required
Three-letter ISO 4217 currency code.
​
product
Product
The Product object this item belongs to.
​
variant
object | null
The Variant object if applicable.
​
offer
Offer | null
The Offer object if this item was purchased through an offer.
​
plan
object | null
The subscription Plan object (variants are used as plans for Subscriptions).
​
internalId
string | null
Your custom identifier for this item.
​
customFields
object
Key-value pairs of custom fields defined by you and filled by the customer during checkout.

​
Example event payload

{
  "id": "evt_123e4567-e89b-12d3-a456-426614174000",
  "type": "payment_success",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
  "testMode": false,
  "data": {
    "items": [
      {
        "object": "item",
        "id": "itm_123e4567-e89b-12d3-a456-426614174001",
        "name": "Pro Plan - Monthly",
        "value": 2999,
        "quantity": 1,
        "currency": "USD",
        "product": {
          "id": "prod_abc123",
          "name": "Pro Plan"
        },
        "variant": null,
        "offer": null,
        "plan": {
          "id": "plan_monthly",
          "name": "Monthly"
        },
        "internalId": "sku_pro_monthly",
        "customFields": {
          "license_type": "single"
        }
      }
    ],
    "order": {
      "object": "order",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "number": "#ABC123DEF456",
      "status": "PAID",
      "value": 2999,
      "currency": "USD"
    },
    "payment": {
      "object": "payment",
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "number": "#PAY123DEF456",
      "status": "PAID"
    },
    "customer": {
      "object": "user",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "email": "customer@example.com",
      "username": null,
      "internalId": "usr_abc123"
    }
  }
}

Webhooks Setup

Configure webhook endpoints

Webhooks Overview

Learn about webhooks

Orders

Order object reference

Payments

Payment object reference