Documentación

Para enviar a Honk basta un solo endpoint, y esta página lo explica entero. Las bibliotecas hacen la misma solicitud, con reintentos y funciones auxiliares.

Inicio rápido

Consigue una cuenta

Por ahora, Honk funciona solo con invitación. Solicita acceso: la invitación te llega por correo e inicias sesión con un código de 6 dígitos.
Crea un proyecto y una clave

En la app web, abre Proyectos y crea uno; después abre su pestaña Claves y crea una clave de ingesta. La clave (honk_…) se muestra una sola vez, así que guárdala enseguida en un lugar seguro.

Envía un evento

Envía JSON por POST con la clave como token bearer. Un 202 significa que Honk ya guardó el evento.

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

Recibe la notificación

Instala Honk para iPhone o activa las notificaciones de la app web en Dispositivos, y envía una prueba con Dame un bocinazo.

La solicitud

POST https://honk-me.app/v1/messages con Content-Type: application/json y Authorization: Bearer <ingestion key>. Los campos desconocidos se rechazan con 422. El cuerpo admite hasta 16 KiB.

Campos

message: Obligatorio. De 1 a 8192 bytes en UTF-8; se conservan los saltos de línea.
title: Una línea, hasta 160 caracteres. Si falta, se usa la primera línea del mensaje.
severity: info, success, warning, error, critical, o los nombres de bocina light, beep, loud, long, blast. Por defecto, info.
priority: low, normal, high o urgent. Por defecto, normal. urgent requiere una clave que lo permita.
group_key: Hasta 128 caracteres. Los eventos con la misma clave (y el mismo proyecto, entorno, origen y canal) forman un grupo.
event_type: event, problem o recovery. Una recuperación requiere un group_key y cierra el problema abierto.
source , environment , channel: Hasta 64, 32 y 64 caracteres. Por defecto, api, default y general.
category: infrastructure, security, backups, deployments, payments, customers, sales, automation, personal o other.
url: Un enlace https:// que se muestra como «Abrir enlace» y solo se abre cuando lo tocas.
image_url: Una imagen https:// que el servidor descarga y muestra con la notificación (hasta 1 MB en Free y 5 MB en Pro y Team).
actions: Hasta 3 botones, en el orden en que se muestran (el primero es el principal), por ejemplo [{"title": "Reply by email", "url": "mailto:[email protected]"}, {"title": "Call", "url": "tel:+12025550147"}]. Cada título tiene de 1 a 40 caracteres; cada URL empieza por https://, mailto:, tel: o sms: y solo se abre cuando tocas su botón.
metadata: Hasta 16 claves con valores de texto, numéricos o booleanos. Las reglas pueden usarlas como condición.
occurred_at: Cuándo ocurrió en el origen, como marca de tiempo RFC 3339.
ttl_seconds: Durante cuánto tiempo se puede seguir entregando la notificación, de 60 a 86 400 segundos. Por defecto, 3600.
source_sequence: Un número creciente por origen, para que una recuperación que llega tarde nunca cierre un problema más reciente.

Respuestas

202	Guardado. `{ "id", "status": "accepted", "duplicate", "received_at" }`. No significa que el evento se haya notificado ni leído.
401	`invalid_key`: la clave es incorrecta o está revocada.
403	`priority_not_allowed`, `project_suspended` o `workspace_suspended`.
409	`idempotency_conflict`: se usó la misma clave con un contenido distinto.
413, 415, 422	Demasiado grande, no es JSON o no es válido: `error.fields` enumera todos los problemas.
429	`quota_exceeded` (el límite diario de mensajes) o `rate_limited`, con `Retry-After`.
503	Honk no puede confirmar ahora mismo que el evento se haya guardado de forma segura. Reintenta con la misma clave cuando pase el tiempo de `Retry-After`.

Reintentar sin duplicados

Envía una cabecera Idempotency-Key (hasta 128 caracteres ASCII imprimibles) que no cambie para un mismo evento, por ejemplo deploy-4812-finished. Durante 24 horas, la misma clave con el mismo contenido devuelve el id original con duplicate: true; la misma clave con un contenido distinto da un 409. Reintenta solo los errores de red, 429 y 5xx, y respeta Retry-After. Las bibliotecas oficiales hacen todo esto por ti.

La gravedad y la escala Honk

Los nombres de bocina son alias. Honk guarda el valor estándar, así que "loud" y "warning" significan lo mismo, también a efectos de idempotencia. error y critical se notifican siempre con prioridad Alta o superior.

Bocinazo suave	`info` · `light`
Bip-bip	`success` · `beep`
Bocinazo fuerte	`warning` · `loud`
Bocinazo largo	`error` · `long`
Bocina sin parar	`critical` · `blast`

Conceptos

Referencia

La API para enviar eventos, como documento OpenAPI 3.1 (openapi.yaml)
Un mapa en texto plano de esta documentación para asistentes de programación (llms.txt)
Los README de las bibliotecas en GitHub: Node.js , PHP / Laravel , Go + CLI , Swift , Kotlin / Java , Rust , n8n

Solo es pública la API para enviar eventos. El resto da servicio a las apps de Honk y puede cambiar entre versiones.