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

# Notifications

> Surface pending device issues to end-users and guide them to resolution

# Notifications

Sometimes a device needs its owner: a manufacturer connection lapses, a subscription runs out, or Podero has something to tell them about how their device is being optimized. This page covers how to build that experience — showing users what needs attention and guiding them through fixing it.

How you *learn* something is pending is up to you: receive a push via [webhooks](/partner-api/notifications/overview) or poll the endpoints below. The journey from there is the same.

## Show a notification badge

[`GET /org/{org_id}/notifications/status`](/partner-api/notifications/reference#get-notification-status) returns pending counts per device type — ideal for badges without fetching full lists:

```bash theme={null}
curl -X GET \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/notifications/status?owner_id={user_id}' \
  -H 'Authorization: Bearer {auth_token}'
```

```json theme={null}
{
  "electric_vehicle": { "action_required": 1, "information_available": 0 },
  "heat_pump": { "action_required": 0, "information_available": 2 },
  "inverter": { "action_required": 0, "information_available": 0 },
  "wallbox": { "action_required": 0, "information_available": 0 }
}
```

`action_required` items block optimization until the user acts; `information_available` items are notices to read. Render them with different urgency.

## List what needs attention

[`GET /org/{org_id}/notifications/actions`](/partner-api/notifications/reference#list-pending-actions) returns everything the user still needs to see, newest first — blocking actions and unread notices merged into one list. Filter with `owner_id`, `device_id`, or `device_type`:

```bash theme={null}
curl -X GET \
  'https://app.podero.com/api/partners/v2.0/org/{org_id}/notifications/actions?owner_id={user_id}' \
  -H 'Authorization: Bearer {auth_token}'
```

Branch on each item's `code`:

| `code`           | What to render                                                                                                   |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `reauthenticate` | A "reconnect your device" prompt — resolving it requires redirecting the user into the manufacturer flow (below) |
| `information`    | A notice card showing `metadata.message`, with a dismiss control                                                 |

<Warning>
  The `secret` inside each `resolution_link.url` is bound to the notification's owner and expires **one hour** after the fetch. Fetch actions when the user opens the view — don't cache the links.
</Warning>

## Resolve a reauthentication

A `reauthenticate` action means the manufacturer connection has lapsed and optimization is paused for that device. Walk the user through reconnecting:

<Steps>
  <Step title="Start the action">
    `POST` to the item's `resolution_link.url` with the parameters named in `required_parameters`:

    ```bash theme={null}
    curl -X POST \
      'https://app.podero.com/api/partners/v2.0/cues/{cue_id}/resolve?secret={secret}' \
      -H 'Content-Type: application/json' \
      -d '{
        "success_url": "https://your-app.example.com/devices/reconnected",
        "cancel_url": "https://your-app.example.com/devices",
        "language": "de"
      }'
    ```

    The response carries the manufacturer flow to send the user into:

    ```json theme={null}
    { "redirect_url": "https://connect.podero.com/..." }
    ```
  </Step>

  <Step title="Redirect the user">
    Send the user to `redirect_url`. They re-authenticate with the manufacturer, then land back on your `success_url` (or `cancel_url` if they abort).
  </Step>

  <Step title="Report the outcome">
    From your `success_url` / `cancel_url` handler, report how it went so the action is marked done (or stays available to retry):

    ```bash theme={null}
    curl -X POST \
      'https://app.podero.com/api/partners/v2.0/cues/{cue_id}/state' \
      -H 'Authorization: Bearer {auth_token}' \
      -H 'Content-Type: application/json' \
      -d '{ "state": "success" }'
    ```

    On `success` the action disappears from the pending list and optimization resumes. On `fail` it stays pending and the user can retry from step 1.
  </Step>
</Steps>

## Dismiss an information notice

Information items need no flow — show `metadata.message` and let the user dismiss it by calling its `resolution_link` (no body required):

```bash theme={null}
curl -X POST \
  'https://app.podero.com/api/partners/v2.0/cues/{notification_id}/information/resolve?secret={secret}'
```

The notice is marked read: it leaves the pending list and the `information_available` count, but stays retrievable in the history via [`GET /notifications/information`](/partner-api/notifications/reference#list-information-notifications) with `dismissed: true`.

## Skip the polling: webhooks

Instead of polling `status`, register a [notification webhook](/partner-api/notifications/integration) and Podero pushes a signed message the moment something needs attention. The message's `data` carries `owner_id`, `device_id`, and `device_type` — pass them straight into the endpoints above to fetch exactly what changed, then notify the right user in your app.

## Next Steps

<CardGroup cols={2}>
  <Card title="Notifications" icon="bell" href="/partner-api/notifications/overview">
    Set up webhook push delivery
  </Card>

  <Card title="Dashboard Integration" icon="chart-line" href="/partner-api/user-journeys/end-user/dashboard-integration">
    Show device status and live readings
  </Card>
</CardGroup>