Skip to main content

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

Integration Guide

Register a webhook, verify signatures, and go live

Reference

Message envelope, headers, topics, and the Webhook Management API

​
How it works

1

You register an endpoint

You call the Webhook Management API 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.
2

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

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

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

You fetch the content and act

The message tells you that a device needs attention; the 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.

​
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. The boundary is who resolves it: only API-resolvable actions ride device.action_required. See the Reference for the full catalogue of action and notice values each topic carries.
Subscribe only to the topics you act on. You can be subscribed to any combination, and each endpoint has its own subscriptions.

​
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 for the full envelope.

​
Notification content

Webhooks are the push side; the 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.

​
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

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

​
Next steps

Integration Guide

Register a webhook, build your receiver, and go live

Reference

Envelope, headers, topics, and the Webhook Management API

Notifications journey

Surface pending items to end-users and guide them to resolution