Publishing

You publish by sending a POST with a JSON body to a topic URL, authenticated with your namespace-scoped API key:

Authorization: Bearer pinglet_<64 hex characters>

There are two ways to address a topic.

Publish by name (recommended)

The simplest form — no /v1, no key in the URL. Your Bearer key is the authority, and the topic is created automatically on first publish if it doesn’t exist:

curl -X POST https://app.pinglet.co.uk/acme/deploys \
  -H "Authorization: Bearer $PINGLET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Deploy done","message":"v1.2.3 is live"}'

This is the URL to hand to any tool that can call a webhook — CI, cron, monitoring, your own app.

Topic names are 1–32 characters of a-z, 0-9, - or _, starting and ending with a letter or digit. A malformed body never creates a topic as a side effect.

Publish by key

The /v1 form addresses a topic by its unguessable key instead of its name. It never auto-creates — publishing to an unknown key returns 404:

curl -X POST https://app.pinglet.co.uk/v1/acme/<topic-key>/publish \
  -H "Authorization: Bearer $PINGLET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Nightly backup finished"}'

The response

Both endpoints return the same shape:

{
  "message_id": 42,
  "topic": "acme/<key>",
  "key": "<key>",
  "name": "deploys",
  "url": "https://app.pinglet.co.uk/acme/deploys/<key>",
  "subscribers": 3,
  "delivered": 3,
  "failed": 0
}

Field	Meaning
`message_id`	The stored message’s id (usable as a `since` cursor when reading history).
`topic`	The capability address `namespace/key` — what subscribed devices store.
`key`	The topic’s unguessable key.
`name`	The topic’s display name, if it has one.
`url`	The shareable subscription link. Hand this to anyone who should receive alerts.
`subscribers`	How many devices were subscribed at publish time.
`delivered` / `failed`	The push fan-out tally for this publish.

Minting a topic up front (optional)

Publishing auto-creates topics, but you can mint one explicitly to get the share link before sending anything:

curl -X POST https://app.pinglet.co.uk/v1/acme/topics \
  -H "Authorization: Bearer $PINGLET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prefix":"deploys"}'

{ "namespace": "acme", "topic": "<key>", "key": "<key>", "name": "deploys" }

Authentication & keys

Keys are minted per-namespace in the web dashboard and shown once at creation. Only the SHA-256 hash is stored server-side.
Keys carry a scope: publish (publish + create topics) or admin (additionally mint and revoke keys).
A leaked key can be revoked immediately from the dashboard — revoked keys stop authenticating at once.

Each publish counts toward your plan’s monthly notification cap. See Plans & errors.

Rewriting third-party webhooks

Some tools emit their own alert JSON. Add ?rewrite=<source> to either publish endpoint and Pinglet translates that tool’s payload into a native message before publishing — no glue service needed. Supported sources: alertmanager, uptimekuma and komodo (Komodo itself can’t authenticate yet — see its guide). An unknown source returns 400. For everything else, the generic webhook recipe works with any tool that can shape its own request.