API de lecture

Le point de terminaison webhook est public et en écriture seule — c'est ainsi que vos applications poussent les alertes vers Zenhook. Pour relire les alertes (créer une CLI, synchroniser avec un autre outil, intégrer un tableau de bord), utilisez l'API authentifiée avec un jeton Bearer.

Authentification

Tous les points de terminaison de lecture nécessitent un jeton Bearer. Les jetons sont limités à une seule paire (utilisateur, espace de travail) — l'accès aux canaux de l'utilisateur (y compris les canaux privés dont il fait partie) est hérité automatiquement.

Générer un jeton

Depuis le tableau de bord : Paramètres → Jetons API → Nouveau jeton. Le jeton complet n'est affiché qu'une seule fois à la création — copiez-le immédiatement. Zenhook ne stocke qu'un hachage SHA-256, donc un jeton perdu ne peut pas être récupéré (révoquez-le et créez-en un nouveau).

Format du jeton

zhk_<48 hex chars>
# example: zhk_a1b2c3d4e5f6...

Envoyer le jeton

bash

curl https://zenhook.dev/api/channels \
  -H "Authorization: Bearer zhk_..."

Lister les canaux

Renvoie les canaux auxquels l'utilisateur du jeton peut accéder (tous les canaux publics ainsi que tout canal privé dont il est explicitement membre). Chaque canal inclut un champ _count.alerts contenant son nombre personnel de messages non lus.

GET https://zenhook.dev/api/channels

Réponses

200 OK

json

[
  {
    "id": "clx_chan_1",
    "name": "production-errors",
    "slug": "production-errors",
    "icon": "🔴",
    "isPrivate": false,
    "webhookToken": "abc123...",
    "_count": { "alerts": 3 }
  }
]

Lister les alertes d'un canal

Paginé, du plus récent au plus ancien. Chaque alerte inclut un booléen isRead calculé pour l'utilisateur appelant — marquer une alerte comme lue n'affecte que votre propre état.

GET https://zenhook.dev/api/channels/{id}/alerts

Paramètres de requête

cursor string

ID d'alerte renvoyé comme nextCursor dans la page précédente. Omettez-le pour la première page.

limit number

1–100. Par défaut 50.

level enum

Filtrer par niveau : info, success, warning, error.

after string

ID d'alerte. Renvoie les alertes strictement plus récentes — utilisé pour le polling.

Réponses

200 OK

json

{
  "alerts": [
    {
      "id": "clx_alert_1",
      "channelId": "clx_chan_1",
      "title": "Build Failed",
      "level": "ERROR",
      "emoji": "🔴",
      "message": "npm install timed out after 300s",
      "fields": [{ "label": "Branch", "value": "main" }],
      "linkUrl": "https://github.com/org/repo/actions/runs/123",
      "isRead": false,
      "createdAt": "2026-04-27T14:32:11.000Z"
    }
  ],
  "nextCursor": "clx_alert_42",
  "hasMore": true
}

Marquer comme lu

L'état de lecture est propre à chaque utilisateur. Marquer une alerte comme lue insère une ligne limitée à l'utilisateur du jeton — les nombres de messages non lus des autres membres de l'espace de travail ne sont pas affectés.

PATCH https://zenhook.dev/api/alerts/{id}

bash

curl -X PATCH https://zenhook.dev/api/alerts/clx_alert_1 \
  -H "Authorization: Bearer zhk_..." \
  -H "Content-Type: application/json" \
  -d '{ "isRead": true }'

Marquer toutes les alertes comme lues

POST https://zenhook.dev/api/alerts/mark-all-read

Le corps est facultatif. Passez { "channelId": "..." } pour limiter à un seul canal ; omettez-le pour marquer comme lus tous les canaux accessibles. Idempotent — relancer est sans effet.

Récupérer une seule alerte

GET https://zenhook.dev/api/alerts/{id}

Renvoie la même structure d'alerte que le point de terminaison de liste, plus le name / slug du canal.

Erreurs

401 Unauthorized — jeton Bearer manquant ou invalide, ou l'utilisateur du jeton n'est plus membre de l'espace de travail.

404 Not Found — la ressource n'existe pas ou l'utilisateur du jeton ne peut pas y accéder (par exemple un canal privé dont il n'est pas membre). Les deux cas sont confondus volontairement afin que les détenteurs de jeton ne puissent pas énumérer les canaux privés.

429 Too Many Requests — limite de débit atteinte. Patientez puis réessayez.

API Webhook