AlphornAlphorn Docs

Send a notification

POST /n/{publicId}: send a notification to Alphorn with JSON or plain text. Request body, Bearer API key auth, status codes, and response format.

POST
/n/{publicId}

Accepts a notification and queues it for delivery to every enabled channel of the webhook whose filter matches. The response returns as soon as the notification is stored; it does not wait for delivery.

The body can be a JSON object (any fields; title, message, priority, and tags are recognized, others are guessed from common field names or mapped with webhook templates), a Slack-compatible payload, or plain text. A body starting with { is parsed as JSON even without a JSON Content-Type.

Checks run in this order and the first failure decides the response: 404, 401, 403, 508, 429, 413, 400.

Authorization

bearerAuth
headerAuthorizationBearer <token>

The webhook's API key (alp_ followed by 64 hex characters). Required unless the webhook was created without one.

Path Parameters

publicId*string

The webhook's public ID, the last segment of its Endpoint URL.

Header Parameters

X-Title?string

Plain-text bodies only: notification title.

X-Priority?string

Plain-text bodies only: priority from 1 to 5.

X-Tags?string

Plain-text bodies only: comma-separated tags.

Request Body

  1. body

Any JSON object is accepted and stored as the message payload. These fields are recognized directly.

title?string

Short title. Truncated to 200 characters.

message?string

Notification body. Truncated to 4,000 characters. If no message is found, the whole body is used.

priority?number

1 (lowest) to 5 (urgent). Rounded and clamped into 1-5. Must be a JSON number; a string is ignored.

Range1 <= value <= 5
tags?array<string>|

Tags for filtering. A comma-separated string also works.

payload?

Extra structured data for payload filters and templates.

[key: string]?any

Response Body

Notification accepted and queued for delivery.

application/json
  1. response
messageId*string

ID of the stored message.

curl -X POST 'https://app.alphorn.dev/n/V1StGXR8_Z5jdHi6B-myT' \  -H 'Content-Type: application/json' \  -d '{  "title": "Claude Code - my-app",  "message": "Needs permission to run the database migration",  "priority": 4,  "tags": [    "ai-agent",    "claude-code",    "permission"  ]}'
{  "messageId": "0199b2f4-3c1e-7a8d-9f20-5d4c3b2a1e0f"}

API Reference

Alphorn HTTP API for sending notifications - endpoint, Bearer API key authentication, JSON, Slack-compatible and plain-text payloads, status codes, and code examples.

Stream notifications (SSE)

GET /api/stream/{publicId}: receive Alphorn notifications in real time over Server-Sent Events. Event format, connection limits, and errors.