Honk
Français
Demander un accès
Demander un accès

Documentation

Un seul endpoint suffit pour envoyer des événements à Honk, et cette page en fait le tour. Les bibliothèques, la CLI et le nœud n8n envoient la même requête, avec en plus les nouvelles tentatives et des helpers, et les guides pas à pas la mettent en place dans WordPress, Home Assistant, cron et la CI.

Démarrage rapide

  1. Obtenir un compte

    Pour l’instant, Honk est sur invitation. Demandez un accès : l’invitation arrive par e-mail, et vous vous connectez avec un code à 6 chiffres.

  2. Créer un projet et une clé

    Dans l’app web, ouvrez Projets, créez-en un, puis ouvrez son onglet Clés et créez une clé d’ingestion. La clé (honk_…) ne s’affiche qu’une fois : notez-la tout de suite en lieu sûr.

  3. Envoyer un événement

    Envoyez du JSON en POST, avec la clé comme jeton Bearer. Une réponse 202 signifie que Honk a enregistré l’événement.

    Terminal 
    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":"…"}

  4. Recevoir le push

    Installez Honk pour iPhone ou activez les notifications dans l’app web, sous Appareils, puis envoyez un test avec Klaxonnez-moi.

La requête

POST https://honk-honk.app/v1/messages avec Content-Type: application/json et Authorization: Bearer <ingestion key>. Les champs inconnus sont refusés avec 422. Le corps ne doit pas dépasser 16 Kio.

Champs

message
Obligatoire. De 1 à 8 192 octets d’UTF-8 ; les retours à la ligne sont conservés.
title
Une ligne, 160 caractères au maximum. Par défaut, la première ligne du message.
severity
info, success, warning, error, critical, ou les noms de klaxon light, beep, loud, long, blast. Par défaut : info.
priority
low, normal, high ou urgent. Par défaut : normal. urgent nécessite une clé qui l’autorise.
group_key
128 caractères au maximum. Les événements qui partagent cette clé (ainsi que le projet, l’environnement, la source et le canal) forment un groupe.
event_type
event, problem ou recovery. Un rétablissement nécessite une group_key et clôt le problème ouvert.
source , environment , channel
Respectivement 64, 32 et 64 caractères au maximum. Par défaut : api, default et general.
category
infrastructure, security, backups, deployments, payments, customers, sales, automation, personal ou other.
url
Un lien https:// affiché sous la forme « Ouvrir le lien », ouvert seulement à votre demande.
image_url
Une image https:// que le serveur récupère et affiche avec la notification (jusqu’à 1 Mo avec Free, 5 Mo avec Pro et Team).
actions
Jusqu’à 3 boutons, dans l’ordre d’affichage (le premier est le principal), par exemple [{"title": "Reply by email", "url": "mailto:[email protected]"}, {"title": "Call", "url": "tel:+12025550147"}]. Un titre compte de 1 à 40 caractères ; une URL commence par https://, mailto:, tel: ou sms: et ne s’ouvre qu’à votre demande.
metadata
16 clés au maximum, avec des valeurs de type texte, nombre ou booléen. Les règles peuvent s’en servir comme conditions.
occurred_at
Le moment où l’événement s’est produit à la source, au format RFC 3339.
ttl_seconds
Combien de temps un push peut encore être distribué, de 60 à 86 400 secondes. Par défaut : 3 600.
source_sequence
Un nombre croissant par source : un rétablissement retardé ne clôt jamais un problème plus récent.

Réponses

202 Enregistré. { "id", "status": "accepted", "duplicate", "received_at" }. Cela ne veut pas dire que l’événement a été envoyé en push ni lu.
401 invalid_key : la clé est incorrecte ou révoquée.
403 priority_not_allowed, project_suspended ou workspace_suspended.
409 idempotency_conflict : la même clé a été utilisée avec un contenu différent.
413, 415, 422 Trop volumineux, pas du JSON, ou invalide : error.fields liste chaque problème.
429 quota_exceeded (la limite quotidienne de messages) ou rate_limited, avec Retry-After.
503 Honk ne peut pas confirmer pour le moment que l’événement a été enregistré. Réessayez avec la même clé après Retry-After.

Réessayer sans risque

Envoyez un en-tête Idempotency-Key (128 caractères ASCII imprimables au maximum) qui reste le même pour un même événement, par exemple deploy-4812-finished. Pendant 24 heures, la même clé avec le même contenu renvoie l’identifiant d’origine avec duplicate: true ; la même clé avec un contenu différent donne un 409. Ne réessayez qu’en cas d’erreur réseau, de 429 ou de 5xx, et respectez Retry-After. Les bibliothèques officielles font tout cela pour vous.

Gravité et échelle Honk

Les noms de klaxon sont des alias. Honk enregistre la valeur standard : "loud" et "warning" sont donc équivalents, y compris pour l’idempotence. error et critical sont toujours envoyés en priorité Haute au minimum.

Petit coup de klaxon info · light
Bip-bip success · beep
Coup de klaxon appuyé warning · loud
Klaxon long error · long
Klaxon continu critical · blast

Concepts

Référence

Seule l’API d’envoi d’événements est publique. Le reste sert aux apps Honk et peut changer d’une version à l’autre.