> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flatpeak.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Required webhooks

After the customer completes the Connect flow, Flatpeak starts to continuously synchronise their tariff data. If any action is needed, Flatpeak sends events via webhooks to your backend so you can prompt the customer to take corrective steps.

## Event types you must handle

Subscribe to these three events:

| Event                       | Description                                                                                                                                                                                                                                 |
| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tariff.expired`            | Emitted when a tariff reaches its end date or becomes invalid. Direct the customer to the [Tariff settings page](/guides/connect/settings-page) to set their current tariff.                                                                |
| `tariff.fetch.failed`       | Emitted after repeated failures to retrieve tariff data from the provider, for example when credentials are invalid or expired. Direct the customer to the [Tariff settings page](/guides/connect/settings-page) to reconnect their tariff. |
| `tariff.connection.upgrade` | Emitted when a higher quality connection becomes available for the provider, typically `DIRECT`. Direct the customer to the [Tariff settings page](/guides/connect/settings-page) to upgrade their tariff connection.                       |
| `location.update`           | Emitted when any data at a location changes, for example prices. Re fetch energy prices or recreate schedules as required by your use case.                                                                                                 |
| `connect_session.complete`  | Emitted when Connect session creates a location ID                                                                                                                                                                                          |

**Example webhook payloads**:

<CodeGroup>
  ```json tariff.expired theme={"system"}
  {
    "id": "evt_6966d693e8d7beb3558bc54a",
    "object": "event",
    "type": "tariff.expired",
    "data": {
      "live_mode": true,
      "location_id": "loc_69661c764a5497be3666d0f6",
      "tariff_id": "trf_69665bd289b104fb993db999",
      "account_id": "acc_67ff7e8e2e5c80a54972fc75"
    }
  }
  ```

  ```json tariff.fetch.failed theme={"system"}
  {
    "id": "evt_6966d6baf5f808d56380160a",
    "object": "event",
    "type": "tariff.fetch.failed",
    "data": {
      "live_mode": true,
      "location_id": "loc_69661c764a5497be3666d0f6",
      "tariff_id": "trf_69665bd289b104fb993db999",
      "account_id": "acc_67ff7e8e2e5c80a54972fc75"
    }
  }
  ```

  ```json tariff.connection.upgrade theme={"system"}
  {
    "id": "evt_6966d5c782f5f6abda2ce3bd",
    "object": "event",
    "type": "tariff.connection.upgrade",
    "data": {
      "live_mode": true,
      "location_id": "loc_69661c764a5497be3666d0f6",
      "tariff_id": "trf_69665bd289b104fb993db999",
      "account_id": "acc_67ff7e8e2e5c80a54972fc75"
    }
  }
  ```

  ```json location.update theme={"system"}
  {
    "id": "evt_6966d6dc33cb60351e443d41",
    "object": "event",
    "type": "location.update",
    "data": {
      <!-- Full payload of retrieve a location endpoint. -->
      "id": "loc_69661c764a5497be3666d0f6",
      "live_mode": true,
      "object": "location"
      "account_id": "acc_67ff7e8e2e5c80a54972fc75"
    }
  }
  ```

  ```json connect_session.complete theme={"system"}
  {
    "id": "evt_6980f0b7dbe7e0f41dbe7353",
    "object": "event",
    "time_created": "2026-02-02T18:45:11Z",
    "type": "connect_session.complete",
    "data": {
      <!-- Full payload of retrieve a token endpoint. -->
      "id": "cot_6980f0abadd87b676f3f027e",
      "live_mode": true,
      "location_id": "loc_6980f0b62a82a9f2e13e8714",
      "object": "connect_session",
    }
  }
  ```
</CodeGroup>

<Info>
  Your systems can continue to access energy prices after the webhooks trigger. Flatpeak [forecasts](/guides/sources/price-forecasts) and extrapolates tariff data until the customer re establishes the tariff connection.
</Info>

To subscribe, go to [Dashboard](https://dashboard.flatpeak.com) > **Webhooks** page.

## When your backend receives `tariff.*` events:

1. **Process the webhook payload** — parse the event and extract `location_id`
2. **Prompt customer action** — notify the user (in-app or by email) with a deep link to the [Tariff Settings Page](/guides/connect/settings-page), asking them to update their tariff connection

<CodeGroup>
  ```json Tariff expired event theme={"system"}
  {
    "id": "evt_66167787c1652b3fbeba5f01",
    "object": "event",
    "type": "tariff.expired"
    "data": {
      "location_id": "loc_661677cdc31d91695fd8f33d",
      "tariff_id": "trf_6597ef46529ab4467502af0b",
      "<truncated for shortness>"
    },
    "time_created": "2024-02-01T11:25:39Z"
  }
  ```

  ```json Tariff fetch failed event theme={"system"}
  {
    "id": "evt_66167787c1652b3fbeba5f01",
    "object": "event",
    "type": "tariff.fetch.failed"
    "data": {
      "location_id": "loc_661677cdc31d91695fd8f33d",
      "tariff_id": "trf_6597ef46529ab4467502af0b",
      "<truncated for shortness>"
    },
    "time_created": "2024-02-01T11:25:39Z"
  }
  ```
</CodeGroup>

## When your backend receives `location.update` events:

1. **Process the webhook payload** — parse the event and extract `location_id`
2. \[[**Re-fetch energy prices or recreate schedules**](/guides/schedule)]\(/guides/schedule) - as needed for your use case

<CodeGroup>
  ```json location update price event theme={"system"}
  {
    "id": "evt_66167787c1652b3fbeba5f01",
    "object": "event",
    "type": "location.update"
      "data": {
      "id": "loc_641b90b758fb8e6293716e40",
      "object": "location",
      "<truncated for shortness>"
    },
    "time_created": "2024-02-01T11:25:39Z"
  }
  ```
</CodeGroup>