Zling

Documentation de l'API

Zling vous permet de recevoir des notifications push HTTP très simplement. Les URL complètes de vos webhooks sont uniques et disponibles directement au sein de l'application iOS Zling.

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 reflète l'infrastructure cloud sécurisée sur laquelle tourne Zling (Convex). Il ressemble à ça :

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ées. 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 POSTavec du texte brut (Plain Text). Ce texte sera alors 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, ce qui est extrêmement pratique pour tester l'alerte manuellement avec votre navigateur. Passez le contenu via le paramètre message (et optionnellement title).

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

Personnalisation avancée avec du 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"
  }'

Voici la liste complète des clés acceptées dans votre payload. Toutes sont paramétrables mais aucune n'est techniquement obligatoire. L'idéal étant de renseigner un message.

title

Chaîne. Le titre principal de la notification tel qu'affiché tout en haut.

subtitle

Chaîne. Le sous-titre de la notification, qui vient s'intercaler sous le titre (supporté principalement sur iOS).

message

Chaîne. Le corps textuel principal de votre notification push.

thread_id

Chaîne. Identifiant d'agrégation. Utiliser le même ID permet d'empiler plusieurs notifications similaires dans une seule "pile" sur l'écran de verrouillage iOS, pour ne pas encombrer l'utilisateur.

open_url

Chaîne. URL standard (https://...) ou deep link local (myapp://...) qui s'ouvrira instantanément au clic sur l'alerte.

image_url

Chaîne. URL d'une ressource image. Apparaîtra en grand format attachée en bas de votre alerte push. Idéal pour des caméras de sécurité ou des graphiques de statut.

expiration_date

Date ISO 8601 temporelle (ex: 2026-04-23T09:00:00.000Z). Assigne une péremption à la notification en transit. Si l'appareil n'a pas eu de réseau depuis l'envoi et dépasse cette date, la notification sera discrètement ignorée par les serveurs d'Apple (APNs).

filter_criteria

Chaîne. Détermine une clé de dérogation logicielle. Lié aux "Modes de Concentration (Focus)" natifs iOS. Permet de faire retentir l'alerte si le Focus en cours autorise ce Tag de contournement spécifique (doit être configuré manuellement côté système).

interruption_level

Détermine le comportement d'interruption du flux de travail de l'utilisateur. Par défaut, le comportement standard iOS est appliqué. Les valeurs possibles sont :

  • passive : Ajouté sans bruit ni allumage d'écran directement au centre des notifications.
  • active : Allume l'écran et produit une vibration/son standard.
  • time-sensitive : Traversera les "résumés planifiés" et potentiellement les blocages de concentration car notifié comme très important pour la période donnée.
  • critical : Niveau le plus élevé. Les alertes critiques sonneront systématiquement même en sourdine. C'est une fonction dédiée presque exclusivement aux alertes médicales, domestiques graves ou de sécurité nationale.

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

Laisser des clés ou "secrets" textuels directement dans l'URL exposée d'une requête n'est pas toujours idéal, puisque divers proxy ou systèmes tiers loggent occasionnellement le trafic par URL complète. Il est préférable de cibler plutôt le point de terminaison racine /v1/send en masquant votre clé d'identification sous l'en-tête natif du protocole Authorization.

Exemple via header

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