HHoller View as Markdown

Holler webhook API

One POST.
Everyone gets the alert.

Create an alert in the Holler iPhone app, share its invite with friends, then publish notifications through its private webhook URL.

Keep the webhook URL private. Anyone who has it can send an alert to every subscriber.
01

Quick start

Copy the webhook URL from your alert and send JSON to it.

curl -X POST "https://holler-api.krill.workers.dev/v1/hooks/YOUR_PUBLISH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: campground-upper-pines-2026-07-18" \
  -d '{
    "title": "Campground available",
    "message": "Upper Pines opened for July 18",
    "url": "https://www.recreation.gov/",
    "image": "https://example.com/upper-pines.jpg"
  }'

A valid event returns 202 Accepted after it is stored and queued. Notification delivery continues in the background.

02

Payload

The request body is intentionally small and fixed.

titlerequired

Sender name shown on the notification. Must be between 1 and 120 characters.

messagerequired

Notification body. Must be between 1 and 500 characters.

urloptional

HTTPS destination opened when someone taps the notification. Maximum 2,000 characters.

imageoptional

Public HTTPS JPEG, PNG, or GIF used as the circular sender avatar. Maximum 5 MB; image failures fall back to the default avatar.

Headers

Content-Typerequired

Must describe a JSON request body.

Idempotency-Keyrecommended

Up to 128 characters. Safe retries with the same key and payload return the original event.

03

Responses

Every API error uses the same JSON shape.

202

Accepted

The event is stored and queued for subscribers.

400

Bad request

Malformed JSON or invalid fields.

413

Too large

The request body is larger than 4 KB.

404

Not found

The webhook is unknown, rotated, deleted, or paused.

409

Conflict

An idempotency key was reused with different content.

429

Rate limited

The webhook burst or creator daily limit was reached.

503

Capacity reached

The service-wide daily safety limit was reached.

{
  "error": {
    "code": "bad_request",
    "message": "Invalid notification",
    "fields": { "title": ["Required"] }
  }
}
04

Free limits

Holler has one free product with fixed safety rails.

3alerts per creator installation
50subscribers per alert
250events per creator per UTC day
30webhook requests per minute

Holler's servers keep events and delivery diagnostics for about 24 hours for delivery processing. There is no server-side event history; each recipient's iPhone separately caches its own received notifications locally for 7 days.

05

Security model

Sharing and publishing use separate capabilities.

Private

Webhook URL

Only give this to the service publishing notifications. Rotate it immediately if it leaks.

Shareable

Invite URL and join code

Send these to friends. They can join the alert, but they cannot publish or manage it.

On device

Creator identity

Holler has no accounts. The anonymous owner token and raw alert credentials stay in iOS SecureStore.

Direct fetch

Notification images

Each recipient’s iPhone downloads the image directly. The image host may observe recipient requests and IP addresses.