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

> Receive real-time notifications from Podero via signed webhooks

# Notifications

Notifications let Podero push events to your systems in real time instead of you polling our API. When something happens to one of your users' devices — for example a device needs the end-user to re-authenticate — Podero sends an HTTP `POST` to an endpoint you control.

Each notification belongs to a **topic**, is scoped to a single **organization**, and is delivered as a signed JSON message so you can verify it genuinely came from Podero.

<CardGroup cols={2}>
  <Card title="Integration Guide" icon="plug" href="/partner-api/notifications/integration">
    Register a webhook, verify signatures, and go live
  </Card>

  <Card title="Reference" icon="code" href="/partner-api/notifications/reference">
    Message envelope, headers, topics, and the Webhook Management API
  </Card>
</CardGroup>

## How it works

<Steps>
  <Step title="You register an endpoint">
    You call the [Webhook Management API](/partner-api/notifications/integration#register-a-webhook) to register an HTTPS URL and the topics you want to receive. The response includes a **signing secret** — shown once, never retrievable again — that you store securely.
  </Step>

  <Step title="An event occurs">
    Something worth telling you about happens within your organization's tenancy — for example a device needs the end-user to act. Podero raises a **notification** under the relevant topic.
  </Step>

  <Step title="Podero delivers a message">
    The notification is fanned out to every endpoint in your organization subscribed to that topic. Each delivery is a single HTTP `POST` carrying a versioned JSON message, signed with your secret.
  </Step>

  <Step title="You acknowledge it">
    Your endpoint verifies the signature, responds with a `2xx` status, and queues the message for processing. Any other response (or a timeout) is treated as a failed delivery.
  </Step>

  <Step title="You fetch the content and act">
    The message tells you *that* a device needs attention; the [Notification Content API](/partner-api/notifications/reference#notification-content-api) tells you *what* is pending. Fetch the pending actions or information notices and surface them to your users, each with a ready-made resolution link.
  </Step>
</Steps>

## Core concepts

### Topics

A **topic** is the category of event you subscribe to. Topics are stable, lowercase-dotted `entity.category` strings and are deliberately coarse — a new kind of event slots into an existing topic rather than growing the contract, and the specific event rides in the message payload for consumers that want to branch further.

| Topic                    | Description                                                                                                                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `device.action_required` | A device needs an action that is resolvable **through Podero's API** before Podero can keep steering or monitoring it — today, re-authentication via the connect flow.                                             |
| `device.information`     | An advisory device update — informational notices, status changes, and issues the user resolves **at the manufacturer** (a lapsed connected-services subscription, disabled remote access, a missing virtual key). |

The boundary is who resolves it: only API-resolvable actions ride `device.action_required`. See the [Reference](/partner-api/notifications/reference#topics) for the full catalogue of `action` and `notice` values each topic carries.

<Tip>
  Subscribe only to the topics you act on. You can be subscribed to any combination, and each endpoint has its own subscriptions.
</Tip>

### Messages

Every delivery is a self-contained **message** — a versioned JSON envelope addressed to one endpoint. It carries a stable `message_id`, the `message_type` (the topic), a `schema_version`, the `occurred_at` timestamp of the originating event, and a topic-specific `data` object. See the [Reference](/partner-api/notifications/reference#message-envelope) for the full envelope.

### Notification content

Webhooks are the **push** side; the [Notification Content API](/partner-api/notifications/reference#notification-content-api) is the **pull** side — the message is the signal to go pull the current pending items and surface them to your users. For the full user-facing flow (badges, action lists, resolving a reauthentication, dismissing notices), see the [Notifications journey](/partner-api/user-journeys/end-user/notifications).

### Organizations

Notifications are strictly tenant-scoped. A notification reaches only the endpoints registered under the organization that owns the source event — never another organization's, even if it happens to subscribe to the same topic.

## Delivery guarantees

<AccordionGroup>
  <Accordion title="At-least-once delivery" icon="repeat">
    Podero guarantees a message is delivered **at least once**. Under some conditions (for example a network hiccup that hides an acknowledgement) you may receive the same message more than once. Every message carries a stable `message_id` — treat it as an **idempotency key** and dedupe on it. See [handling duplicates](/partner-api/notifications/integration#4-handle-duplicates).
  </Accordion>

  <Accordion title="Signed and verifiable" icon="shield-check">
    Every message is signed with an HMAC-SHA256 signature over the exact request body, carried in the `X-Podero-Signature` header alongside a timestamp. Verifying the signature proves the message came from Podero and was not altered in transit, and the timestamp lets you reject replays. See [verifying signatures](/partner-api/notifications/integration#verifying-the-signature).
  </Accordion>

  <Accordion title="HTTPS only" icon="lock">
    Endpoints must be reachable over HTTPS with a valid certificate. Podero validates the destination address on every delivery and refuses to connect to private, loopback, link-local, or cloud-metadata addresses.
  </Accordion>

  <Accordion title="Order is not guaranteed" icon="arrow-down-wide-short">
    Messages are delivered independently. Do not rely on receiving them in the order the underlying events occurred — use each message's `occurred_at` timestamp if ordering matters to you.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Integration Guide" icon="plug" href="/partner-api/notifications/integration">
    Register a webhook, build your receiver, and go live
  </Card>

  <Card title="Reference" icon="code" href="/partner-api/notifications/reference">
    Envelope, headers, topics, and the Webhook Management API
  </Card>

  <Card title="Notifications journey" icon="bell" href="/partner-api/user-journeys/end-user/notifications">
    Surface pending items to end-users and guide them to resolution
  </Card>
</CardGroup>