Documentation de l'API

Fonctionnement de vos webhooks

Dans l'application Zling, vous trouverez deux types de webhooks :

• Webhook partagé (br_usr_...) : envoie la notification vers tous vos appareils en une seule fois.
• Webhook appareil (br_dev_...) : cible un seul appareil spécifique.

Le domaine de votre webhook ressemble à ceci :

https://<votre-projet>.convex.site/v1/br_usr_abc123def456ghi789

⚠️ Attention : toute personne possédant ce lien complet peut vous envoyer des notifications. Gardez vos secrets privés. En cas de fuite, vous pouvez facilement révoquer et générer de nouveaux secrets dans l'onglet « Paramètres » ou en cliquant sur « Rotation » dans l'application.

Envoyer une notification push (Texte brut)

La méthode la plus rapide est d'effectuer une requête POST avec du texte brut (text/plain). Ce texte sera assigné comme message principal de l'alerte.

Exemple avec cURL

curl -X POST https://<votre-projet>.convex.site/v1/br_usr_abc123def456ghi789 \
  -H "Content-Type: text/plain" \
  -d 'Déploiement terminé avec succès ! 🚀'

Vous pouvez également déclencher une notification via une simple requête GET, pratique pour tester l'alerte manuellement depuis un navigateur. Passez le contenu via les paramètres message et title :

https://<votre-projet>.convex.site/v1/br_usr_abc123def456ghi789?message=Test%20rapide%20!&title=Salut

Personnalisation avancée avec JSON

Pour davantage de flexibilité (titres, images, liens, priorités), envoyez un payload formaté en JSON (application/json).

Exemple cURL

curl -X POST https://<votre-projet>.convex.site/v1/br_usr_abc123def456ghi789 \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Alerte de surveillance",
    "subtitle": "Serveur de production",
    "message": "L\'utilisation du CPU a dépassé les 90%.",
    "thread_id": "monitoring-alerts",
    "interruption_level": "time-sensitive",
    "open_url": "https://dashboard.mon-app.com"
  }'

Liste complète des paramètres

Tous les paramètres sont optionnels. L'idéal est de toujours renseigner un message.

Niveaux d'interruption (interruption_level)

Note : le niveau critical n'est pas supporté par Zling. Il nécessite une autorisation spéciale Apple réservée aux applications médicales, de sécurité domestique ou de sécurité nationale. Si vous envoyez "critical", l'API retournera une erreur 400 avec la liste des valeurs autorisées.

Limites et codes d'erreur

Passer le secret de façon sécurisée

Exposer un secret directement dans l'URL n'est pas idéal (certains proxy ou services tiers loguent les URL complètes). Il est préférable d'utiliser l'endpoint racine /v1/send avec le header Authorization :

Exemple via header Authorization

curl -X POST https://<votre-projet>.convex.site/v1/send \
  -H 'Authorization: Bearer br_usr_abc123def456ghi789' \
  -H 'Content-Type: application/json' \
  -d '{"message": "Envoi sécurisé via Bearer token !"}'

Cette méthode fonctionne également en GET :

curl -G https://<votre-projet>.convex.site/v1/send \
  -H 'Authorization: Bearer br_usr_abc123def456ghi789' \
  --data-urlencode 'message=Test rapide' \
  --data-urlencode 'title=Salut'

Endpoints disponibles