# Honk docs: sending events

> Sending to Honk takes one endpoint, and this page covers all of it. The libraries, the CLI and the n8n node wrap the same request with retries and helpers, and the step-by-step guides set it up in WordPress, Home Assistant, cron and CI.

Source: https://honk-honk.app/docs

## Quickstart

1. **Get an account.** Honk is invite-only for now. Request access; the invitation arrives by email and you sign in with a 6-digit code.
2. **Create a project and a key.** In the web app, open Projects, create one, then open its Keys tab and create an ingestion key. The key (honk_…) is shown only once, so save it somewhere safe right away.
3. **Send an event.** Post JSON with the key as a bearer token. A 202 means Honk has saved the event.
4. **Get the push.** Install Honk for iPhone or enable notifications in the web app under Devices, then send a test with Honk me.

```sh
curl -sS https://honk-honk.app/v1/messages \
  -H "Authorization: Bearer $HONK_KEY" \
  -H "Idempotency-Key: backup-$(date +%Y%m%d)" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backup failed",
    "message": "pg_dump exited with 1",
    "severity": "long",
    "group_key": "db/backup",
    "event_type": "problem"
  }'
# → 202 {"id":"msg_…","status":"accepted","duplicate":false,"received_at":"…"}
```

## The request

`POST https://honk-honk.app/v1/messages` with `Content-Type: application/json` and `Authorization: Bearer <ingestion key>`. Unknown fields are rejected with `422`. The body can be up to 16 KiB.

| Field | Notes |
|---|---|
| `message` | Required. 1 to 8192 bytes of UTF-8; line breaks are kept. |
| `title` | One line, up to 160 characters. Defaults to the first line of the message. |
| `severity` | `info`, `success`, `warning`, `error`, `critical`, or the horn names `light`, `beep`, `loud`, `long`, `blast`. Defaults to `info`. |
| `priority` | `low`, `normal`, `high` or `urgent`. Defaults to `normal`. `urgent` needs a key that allows it. |
| `group_key` | Up to 128 characters. Events with the same key (and project, environment, source, channel) form one group. |
| `event_type` | `event`, `problem` or `recovery`. A recovery needs a `group_key` and closes the open problem. |
| `source, environment, channel` | Up to 64, 32 and 64 characters. Defaults: `api`, `default` and `general`. |
| `category` | `infrastructure`, `security`, `backups`, `deployments`, `payments`, `customers`, `sales`, `automation`, `personal` or `other`. |
| `url` | An `https://` link shown as “Open link”, opened only when you tap it. |
| `image_url` | An `https://` image the server fetches and shows with the notification (up to 1 MB on Free, 5 MB on Pro and Team). |
| `actions` | Up to 3 buttons in display order (the first is the main one), for example `[{"title": "Reply by email", "url": "mailto:emily@example.com"}, {"title": "Call", "url": "tel:+12025550147"}]`. A title has 1 to 40 characters; a URL starts with `https://`, `mailto:`, `tel:` or `sms:` and opens only when you tap its button. |
| `metadata` | Up to 16 keys with string, number or boolean values. Rules can match on them. |
| `occurred_at` | When it happened at the source, as an RFC 3339 timestamp. |
| `ttl_seconds` | How long a push can still be delivered, from 60 to 86400 seconds. Defaults to 3600. |
| `source_sequence` | An increasing number per source, so a delayed recovery never closes a newer problem. |

## Responses

| Status | Meaning |
|---|---|
| 202 | Stored. `{ "id", "status": "accepted", "duplicate", "received_at" }`. It doesn’t mean the event was pushed or read. |
| 401 | `invalid_key`: the key is wrong or revoked. |
| 403 | `priority_not_allowed`, `project_suspended` or `workspace_suspended`. |
| 409 | `idempotency_conflict`: the same key was used with a different payload. |
| 413, 415, 422 | Too large, not JSON, or invalid: `error.fields` lists every problem. |
| 429 | `quota_exceeded` (the daily message limit) or `rate_limited`, with `Retry-After`. |
| 503 | Honk can’t confirm right now that the event was saved safely. Retry with the same key after `Retry-After`. |

## Retrying safely

Send an `Idempotency-Key` header (up to 128 printable ASCII characters) that stays the same for the same event, for example `deploy-4812-finished`. Within 24 hours, the same key with the same payload returns the original id with `duplicate: true`; the same key with a different payload is a `409`. Retry only network errors, `429` and `5xx`, and honor `Retry-After`. The official libraries do all of this for you.

## Severity and the Honk scale

The horn names are aliases. Honk stores the standard value, so `"loud"` and `"warning"` mean the same thing, including for idempotency. `error` and `critical` are always pushed at High priority or above.

| Canonical | Alias | Name |
|---|---|---|
| `info` | `light` | Light honk |
| `success` | `beep` | Beep-beep |
| `warning` | `loud` | Loud honk |
| `error` | `long` | Long honk |
| `critical` | `blast` | Blast |

## Reference

- OpenAPI 3.1: https://honk-honk.app/docs/openapi.yaml
- Libraries: https://github.com/honk-hq/node, https://github.com/honk-hq/php, https://github.com/honk-hq/go, https://github.com/honk-hq/honk-swift, https://github.com/honk-hq/kotlin, https://github.com/honk-hq/rust, https://github.com/honk-hq/n8n

Only the API for sending events is public. The rest serves the Honk apps and may change between versions.