# Events

Events allow your applications to receive notifications as activity occurs in your Openfort accounts, enabling your backend systems to execute actions accordingly.

Configure notifications via the API or from the dashboard to receive events from your Openfort account or on-chain activity.

By default, Openfort sends a notification to the specified subscriptions every 24 hours.

:::tip
You can configure everything on this page from the dashboard under **Notifications**: register delivery endpoints on the [**Webhooks**](https://dashboard.openfort.io/webhooks) tab, and set balance thresholds on the [**Events**](https://dashboard.openfort.io/events) tab.
:::

## How it fits together

Three objects work together to deliver a notification:

* **Subscription**: binds a **topic** (what you want to hear about) to one or more **triggers**. Created via `POST /v1/subscriptions`.
* **Trigger**: a single **delivery destination** on a subscription — a webhook URL or an email address. Created via `POST /v1/subscriptions/{id}/triggers`.
* **Event**: the **threshold** that decides *when* a balance topic fires. Created via `POST /v1/events`.

A subscription says *what* and *where*; a trigger is one of those *where* destinations; an event is the *when*. Balance alerts (`balance.project`, `balance.contract`, `balance.dev_account`) need both a subscription and an event.

## Create a subscription

A subscription binds a topic to an initial set of triggers. Create one with the topic and at least one delivery destination.

:::code-group
```bash [command-line]
curl https://api.openfort.io/v1/subscriptions \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "balance.project",
    "triggers": [{"target": "{{EMAIL_ADDRESS}}", "type": "email"}]
  }'
```

```ts [server.ts]
import Openfort from '@openfort/openfort-node';
const openfort = new Openfort(YOUR_SECRET_KEY);

const subscription = await openfort.subscriptions.create({
  topic: "balance.project",
  triggers: [
    {
      target: "{{EMAIL_ADDRESS}}",
      type: "email",
    },
  ],
})
```
:::

## Add a trigger

A trigger is a single delivery destination on a subscription. Two types are available:

* **Webhook**: Openfort sends a POST request to your URL. See the [webhooks guide](/docs/configuration/webhooks) to receive and verify them.
* **Email**: Openfort sends an email to the address.

A subscription can have more than one trigger, so the same topic can be delivered to several destinations.

:::code-group
```bash [Webhook]
curl https://api.openfort.io/v1/subscriptions/sub_.../triggers \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://your-server.com/webhooks/openfort",
    "type": "webhook"
  }'
```

```bash [Email]
curl https://api.openfort.io/v1/subscriptions/sub_.../triggers \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "{{EMAIL_ADDRESS}}",
    "type": "email"
  }'
```

```ts [server.ts]
import Openfort from '@openfort/openfort-node';
const openfort = new Openfort(YOUR_SECRET_KEY);

const trigger = await openfort.triggers.create(
  "sub_e0b84653-1741-4a3d-9e91-2b0fd2942f60",
  {
    target: "https://your-server.com/webhooks/openfort",
    type: "webhook",
  },
)
```
:::

## Set a balance threshold

The balance topics — `balance.project`, `balance.contract`, and `balance.dev_account` — only fire once you define **how low** the balance must get. That condition is an **event**: it holds the threshold (and, for contract and backend-wallet alerts, the chain, contract, or wallet to watch).

A subscription tells Openfort *where* to deliver the notification; an event tells Openfort *when* to send it. A balance alert needs both.

### Project balance

The project balance threshold is a single value in USD. Openfort notifies your subscriptions when your remaining project credits drop below it, so you can keep sponsoring gas fees for your users.

:::code-group
```bash [command-line]
curl https://api.openfort.io/v1/events \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "balance.project",
    "name": "Project balance event",
    "threshold": "10"
  }'
```
:::

### Contract and backend-wallet balance

Contract and backend-wallet thresholds are denominated in wei and target a specific chain. A contract event compares the return value of a contract function against the threshold (useful to watch a paymaster's deposit); a backend-wallet event watches the native balance of a wallet that pays gas for onchain transactions.

:::code-group
```bash [Contract balance]
curl https://api.openfort.io/v1/events \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "balance.contract",
    "name": "Contract balance event",
    "threshold": "1000000000000000000",
    "chainId": 80002,
    "contract": "con_...",
    "functionName": "getDeposit"
  }'
```

```bash [Backend wallet balance]
curl https://api.openfort.io/v1/events \
  -H "Authorization: Bearer $YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "balance.dev_account",
    "name": "Wallet balance event",
    "threshold": "1000000000000000000",
    "chainId": 80002,
    "developerAccount": "dac_..."
  }'
```
:::

:::tip
Every threshold you create is listed — and editable — in the dashboard under [**Notifications → Events**](https://dashboard.openfort.io/events). The project balance threshold shows in its own card; contract and backend-wallet thresholds appear in their respective tables.
:::