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
idfor deduplication - An
idempotencyKeyto prevent duplicate processing - The event
typeindicating what happened - A
datapayload 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 Type | Description |
|---|---|
payment_success | A Payment has been successfully processed. Use this to fulfill orders and grant subscription access. |
payment_refunded | A Payment has been refunded (full or partial) |
payment_failed | A Payment attempt has failed |
subscription_created | A new Subscription record exists in Stripe/Fungies. May include PENDING payment data if sent before checkout finishes — not a paid signal by itself. |
subscription_interval | A Subscription's billing interval has been charged |
subscription_updated | A Subscription has been modified |
subscription_cancelled | A 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.lastPaymentanddata.ordermay still bePENDING.payment_success— initialsubscription_initialpayment isPAID; 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
idstringrequiredUnique identifier (UUID) for this event.
typestringrequiredThe type of event that occurred. See Event types above.
idempotencyKeystringrequiredUnique key (UUID) for idempotent event processing. Use this to prevent duplicate handling of the same event.
testModebooleanrequiredWhether this event occurred in test mode (true) or live mode (false).
dataobjectrequiredThe event payload containing related objects.
data properties
itemsarrayrequiredArray of line items involved in the transaction. See Item object below.
orderOrderrequiredThe Order object associated with this event.
paymentPaymentrequiredThe Payment object for the transaction.
customerUserrequiredThe User object representing the customer.
Item object
Each item in the data.items array represents a line item in the Order.
objectstringObject type identifier. Always "item".
idstringrequiredUnique identifier (UUID) for this line item.
namestringrequiredDisplay name of the item.
valueintegerrequiredItem price in the smallest currency unit. Defaults to 0.
quantityintegerrequiredNumber of units purchased.
currencystringrequiredThree-letter ISO 4217 currency code.
productProductThe Product object this item belongs to.
variantobject | nullThe Variant object if applicable.
offerOffer | nullThe Offer object if this item was purchased through an offer.
planobject | nullThe subscription Plan object (variants are used as plans for Subscriptions).
internalIdstring | nullYour custom identifier for this item.
customFieldsobjectKey-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
{
"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"
}
}
}Related resources
Last updated