> ## 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.

# 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](/core-resources/payment) or [Subscription](/core-resources/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](/core-resources/order), 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

<Note>
  Events may be delivered more than once. Use the `idempotencyKey` to ensure you process each event only once.
</Note>

## 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](/core-resources/payment) has been successfully processed. **Use this to fulfill orders and grant subscription access.**                                                    |
| `payment_refunded`       | A [Payment](/core-resources/payment) has been refunded (full or partial)                                                                                                               |
| `payment_failed`         | A [Payment](/core-resources/payment) attempt has failed                                                                                                                                |
| `subscription_created`   | A new [Subscription](/core-resources/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](/core-resources/subscription)'s billing interval has been charged                                                                                                     |
| `subscription_updated`   | A [Subscription](/core-resources/subscription) has been modified                                                                                                                       |
| `subscription_cancelled` | A [Subscription](/core-resources/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.

<Note>
  Treat `subscription_created` as informational (lifecycle, CRM, analytics). Treat `payment_success` as the fulfillment trigger for the first charge.
</Note>

***

## The Event object

<ResponseField name="id" type="string" required>
  Unique identifier (UUID) for this event.
</ResponseField>

<ResponseField name="type" type="string" required>
  The type of event that occurred. See [Event types](#event-types) above.
</ResponseField>

<ResponseField name="idempotencyKey" type="string" required>
  Unique key (UUID) for idempotent event processing. Use this to prevent duplicate handling of the same event.
</ResponseField>

<ResponseField name="testMode" type="boolean" required>
  Whether this event occurred in test mode (`true`) or live mode (`false`).
</ResponseField>

<ResponseField name="data" type="object" required>
  The event payload containing related objects.

  <Expandable title="data properties">
    <ResponseField name="items" type="array" required>
      Array of line items involved in the transaction. See [Item object](#item-object) below.
    </ResponseField>

    <ResponseField name="order" type="Order" required>
      The [Order object](/core-resources/order) associated with this event.
    </ResponseField>

    <ResponseField name="payment" type="Payment" required>
      The [Payment object](/core-resources/payment) for the transaction.
    </ResponseField>

    <ResponseField name="customer" type="User" required>
      The [User object](/core-resources/user) representing the customer.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Item object

Each item in the `data.items` array represents a line item in the [Order](/core-resources/order).

<ResponseField name="object" type="string">
  Object type identifier. Always `"item"`.
</ResponseField>

<ResponseField name="id" type="string" required>
  Unique identifier (UUID) for this line item.
</ResponseField>

<ResponseField name="name" type="string" required>
  Display name of the item.
</ResponseField>

<ResponseField name="value" type="integer" required>
  Item price in the smallest currency unit. Defaults to `0`.
</ResponseField>

<ResponseField name="quantity" type="integer" required>
  Number of units purchased.
</ResponseField>

<ResponseField name="currency" type="string" required>
  Three-letter ISO 4217 currency code.
</ResponseField>

<ResponseField name="product" type="Product">
  The [Product object](/core-resources/product) this item belongs to.
</ResponseField>

<ResponseField name="variant" type="object | null">
  The Variant object if applicable.
</ResponseField>

<ResponseField name="offer" type="Offer | null">
  The [Offer object](/core-resources/offer) if this item was purchased through an offer.
</ResponseField>

<ResponseField name="plan" type="object | null">
  The subscription Plan object (variants are used as plans for [Subscriptions](/core-resources/subscription)).
</ResponseField>

<ResponseField name="internalId" type="string | null">
  Your custom identifier for this item.
</ResponseField>

<ResponseField name="customFields" type="object">
  Key-value pairs of custom fields defined by you and filled by the customer during checkout.
</ResponseField>

***

## Example event payload

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Webhooks Setup" icon="webhook" href="/developers/webhooks/setup">
    Configure webhook endpoints
  </Card>

  <Card title="Webhooks Overview" icon="book" href="/developers/webhooks/overview">
    Learn about webhooks
  </Card>

  <Card title="Orders" icon="receipt" href="/core-resources/order">
    Order object reference
  </Card>

  <Card title="Payments" icon="credit-card" href="/core-resources/payment">
    Payment object reference
  </Card>
</CardGroup>