Documentație

Ca să trimiți ceva către Honk îți trebuie un singur endpoint, iar pagina asta îl descrie complet. Bibliotecile fac aceeași cerere, cu reîncercări și helpere în plus.

Pornire rapidă

Obține un cont

Deocamdată, Honk e disponibil doar pe bază de invitație. Cere acces; invitația vine pe email și te autentifici cu un cod din 6 cifre.
Creează un proiect și o cheie

În aplicația web, deschide Proiecte, creează un proiect, apoi deschide fila Chei și creează o cheie API. Cheia (honk_…) apare o singură dată, așa că pune-o imediat într-un loc sigur.

Trimite un eveniment

Trimite un JSON prin POST, cu cheia ca token Bearer. Un 202 înseamnă că Honk a salvat evenimentul.

Terminal

curl -sS https://honk-me.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":"…"}

Primește notificarea

Instalează Honk pentru iPhone sau activează notificările în aplicația web, la Dispozitive, apoi trimite un test cu Claxonează-mă.

Cererea

POST https://honk-me.app/v1/messages cu Content-Type: application/json și Authorization: Bearer <ingestion key>. Câmpurile necunoscute sunt respinse cu 422. Corpul cererii poate avea cel mult 16 KiB.

Câmpuri

message: Obligatoriu. Între 1 și 8192 de octeți UTF-8; rândurile noi se păstrează.
title: Un singur rând, cel mult 160 de caractere. Implicit, primul rând al mesajului.
severity: info, success, warning, error, critical sau numele de claxon light, beep, loud, long, blast. Implicit info.
priority: low, normal, high sau urgent. Implicit normal. urgent cere o cheie care îl permite.
group_key: Cel mult 128 de caractere. Evenimentele cu aceeași cheie (și același proiect, mediu, sursă și canal) formează un grup.
event_type: event, problem sau recovery. O revenire cere un group_key și închide problema deschisă.
source , environment , channel: Cel mult 64, 32 și 64 de caractere. Valori implicite: api, default și general.
category: infrastructure, security, backups, deployments, payments, customers, sales, automation, personal sau other.
url: Un link https:// afișat ca „Deschide linkul” și deschis doar când apeși pe el.
image_url: O imagine https:// pe care serverul o descarcă și o afișează cu notificarea (cel mult 1 MB pe Free, 5 MB pe Pro și Team).
actions: Cel mult 3 butoane, în ordinea afișării (primul e cel principal), de exemplu [{"title": "Reply by email", "url": "mailto:[email protected]"}, {"title": "Call", "url": "tel:+12025550147"}]. Un titlu are între 1 și 40 de caractere; un URL începe cu https://, mailto:, tel: sau sms: și se deschide doar când apeși pe butonul lui.
metadata: Cel mult 16 chei, cu valori de tip șir, număr sau boolean. Regulile pot filtra după ele.
occurred_at: Momentul în care s-a întâmplat la sursă, în format RFC 3339.
ttl_seconds: Cât timp mai poate fi livrată notificarea, între 60 și 86400 de secunde. Implicit 3600.
source_sequence: Un număr crescător pentru fiecare sursă, ca o revenire întârziată să nu închidă niciodată o problemă mai nouă.

Răspunsuri

202	Salvat. `{ "id", "status": "accepted", "duplicate", "received_at" }`. Nu înseamnă că evenimentul a fost trimis ca notificare sau citit.
401	`invalid_key`: cheia este greșită sau revocată.
403	`priority_not_allowed`, `project_suspended` sau `workspace_suspended`.
409	`idempotency_conflict`: aceeași cheie a fost folosită cu alt conținut.
413, 415, 422	Prea mare, nu este JSON sau este invalid: `error.fields` listează fiecare problemă.
429	`quota_exceeded` (limita zilnică de mesaje) sau `rate_limited`, cu `Retry-After`.
503	Honk nu poate confirma acum că evenimentul a fost salvat în siguranță. Reîncearcă cu aceeași cheie după `Retry-After`.

Reîncercări sigure

Trimite un header Idempotency-Key (cel mult 128 de caractere ASCII afișabile) care rămâne același pentru același eveniment, de exemplu deploy-4812-finished. Timp de 24 de ore, aceeași cheie cu același conținut întoarce id-ul original cu duplicate: true; aceeași cheie cu alt conținut primește 409. Reîncearcă doar la erori de rețea, 429 și 5xx și respectă Retry-After. Bibliotecile oficiale fac toate acestea pentru tine.

Gravitatea și scala Honk

Numele de claxon sunt doar alias-uri. Honk salvează valoarea standard, așa că "loud" și "warning" înseamnă același lucru, inclusiv pentru idempotență. error și critical pleacă mereu cu prioritate cel puțin Ridicată.

Claxon ușor	`info` · `light`
Bip-bip	`success` · `beep`
Claxon puternic	`warning` · `loud`
Claxon lung	`error` · `long`
Claxon continuu	`critical` · `blast`

Concepte

Referință

API-ul pentru trimiterea evenimentelor, ca document OpenAPI 3.1 (openapi.yaml)
O hartă în text simplu a acestei documentații, pentru asistenții de programare (llms.txt)
Fișierele README ale bibliotecilor, pe GitHub: Node.js , PHP / Laravel , Go + CLI , Swift , Kotlin / Java , Rust , n8n

Doar API-ul pentru trimiterea evenimentelor e public. Restul servește aplicațiile Honk și se poate schimba de la o versiune la alta.