Référence API

Un seul endpoint, une seule requête POST. Envoyez du JSON à l'URL de webhook de votre canal et nous gérons les notifications, la mise en forme et la distribution.

Envoyer une alerte

Déclenchez une nouvelle alerte dans un canal spécifique. C'est l'endpoint principal pour envoyer des notifications depuis votre application.

POSThttps://zenhook.dev/api/webhook/{token}
Exemple de requête
curl -X POST https://zenhook.dev/api/webhook/abc123def456 \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New User Signup",
    "level": "success",
    "emoji": "🎉",
    "source": "My App",
    "message": "[email protected] just joined your workspace.",
    "linkUrl": "https://myapp.com/admin/users/42",
    "linkText": "View Profile"
  }'

Paramètres de chemin

tokenstringRequis
Le jeton de webhook unique de votre canal. Vous le trouverez dans les paramètres du canal.

Corps de la requête

titlestringRequis
Un bref résumé de l'alerte. Utilisé comme titre dans les notifications. 200 caractères maximum.
levelenum
Niveau de gravité de l'alerte : info, success, warning, error. Par défaut info.
messagestring
Corps de texte détaillé. 5 000 caractères maximum.
emojistring
Emoji personnalisé affiché à côté du titre. Accepte un caractère unicode ("🚀"), un nom ("rocket"), ou un shortcode (":rocket:"). Les noms et shortcodes sont convertis à l'ingestion. Les noms inconnus sont ignorés plutôt qu'affichés comme texte littéral. Noms reconnus : rocket · siren · warning · check · cross · fire · bug · zap · bell · tada · sparkles · envelope · chat · phone · megaphone · wave · eyes · heart · thumbsup · office · door · house · factory · lock · unlock · key · link · package · gear · wrench · shield · money · chart · clock · hourglass · flag · star · target · pin · tag · computer · server · database · cloud · bulb · gem · anchor · pick · bank.
fieldsarray
Objets clé-valeur pour les données structurées. Chaque objet contient label et value.
linkUrlstring
URL d'un lien d'appel à l'action cliquable affiché sous le titre.
linkTextstring
Libellé du bouton du lien. Par défaut "View" si linkUrl est défini.
attachmentsarray
Jusqu'à 8 médias affichés dans l'alerte. Chaque objet prend une url et, en option, untype(image,video ouaudio) et une légendename. Zenhook récupère chaque URL et réhéberge le fichier sur son propre CDN — vos médias se chargent vite et vos URLs sources restent privées. Formats acceptés : PNG, JPEG, GIF, WebP, AVIF, MP4, WebM, MP3, WAV, M4A, Ogg (le SVG est refusé). Max 10 Mo par image, 25 Mo audio, 50 Mo vidéo.
Envoi direct de fichiersmultipart
Pas d'URL publique pour votre fichier ? Envoyez les octets directement. POSTez enmultipart/form-data avec une partpayload portant les mêmes champs JSON, plus une part fichier par pièce jointe. Le client le plus simple, c'est un titre et un fichier :
curl -X POST https://zenhook.dev/api/webhook/YOUR_TOKEN \
  -F 'payload={"title":"Build failed","level":"error"}' \
  -F 'file=@./screenshot.png'
Mêmes limites que les pièces jointes par URL : jusqu'à 8 fichiers, 10 Mo par image, 25 Mo audio, 50 Mo vidéo.
sourcestring
Nom de l'auteur affiché dans l'en-tête de l'alerte (par ex. "GitHub", "Stripe"). Par défaut "Webhook".
metadataobject
Objet JSON arbitraire affiché dans une section dépliable "Raw Payload" avec copie dans le presse-papiers. 10 Ko maximum.

Réponses

201 Created

Alerte reçue et mise en file d'attente pour distribution.

json
{
  "success": true,
  "alertId": "clx1234567890abcdef",
  "queuedAt": "2024-03-22T12:00:00Z"
}

Notifications de workflow

Un déploiement ou une release est un seul processus, pas cinq alertes. Ajoutez un blocworkflow et chaque POST portant le mêmerunId met à jour une seule alerte : la carte montre chaque étape en direct, et le flux ne se remplit jamais de bruit intermédiaire.

bash
# every POST of a run carries the same runId
curl -X POST https://zenhook.dev/api/webhook/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "title": "myapp deploy",
    "workflow": {
      "runId": "myapp-20260722-1015",
      "state": "running",
      "steps": [
        { "name": "test",   "state": "done",    "seconds": 46, "info": "716 tests" },
        { "name": "build",  "state": "running" },
        { "name": "deploy", "state": "pending" }
      ]
    }
  }'

États : le run est running, passed ou failed ; chaque étape est pending, running, done, failed ou skipped. Envoyez le tableau d'étapes COMPLET à chaque fois ; le serveur remplace, il ne fusionne jamais.

Politique de notification : le premier POST notifie (démarré), les mises à jour en cours sont silencieuses, et l'état final notifie une fois et refait remonter l'alerte comme non lue. Le niveau est dérivé de l'état : un run échoué ne peut jamais prétendre avoir réussi.

Facturation : un processus est un seul événement, compté au premier POST. Les mises à jour sont gratuites.

En cas d'échec : passez workflow.error avec la fin du log ; elle s'affiche sur la carte pour diagnostiquer depuis un téléphone.

Données structurées

Utilisez le tableau fields pour inclure des métadonnées riches affichées dans le tableau de bord et les alertes par e-mail.

Exemple avec fields
{
  "title": "Build Failed",
  "level": "error",
  "fields": [
    { "label": "Branch", "value": "main" },
    { "label": "Commit", "value": "abc123f" },
    { "label": "Author", "value": "John Smith" },
    { "label": "Error", "value": "npm install timed out after 300s" }
  ],
  "attachments": [
    { "url": "https://ci.example.com/runs/123/screenshot.png", "type": "image" }
  ],
  "linkUrl": "https://github.com/org/repo/actions/runs/123",
  "linkText": "View Logs"
}

Relire les alertes

L'endpoint de webhook ci-dessus est public et en écriture seule, toute personne disposant du jeton du canal peut y publier. Pour lister les alertes, les marquer comme lues ou construire une intégration qui les consomme, utilisez l' API de lecture authentifiée avec un jeton Bearer.

Premiers pas