Canaux

Un canal est une destination d’alertes. Une règle en vise au moins un ; un canal peut servir à plusieurs règles.

`kind`	Destination	Création par l’API
`webhook`	Votre serveur HTTPS, requêtes signées.	Directe (`201`), avec `url`.
`discord`	Un salon Discord, par un webhook entrant.	Directe (`201`), avec `url`.
`slack`	Un canal Slack, par un incoming webhook.	Directe (`201`), avec `url`.
`email`	1 à 10 adresses email.	Directe (`201`), avec `emails`.
`telegram`	Un groupe ou une conversation Telegram.	Par lien d’invitation (`202`).
`hellome`	Une conversation helloMe.	Par lien d’invitation (`202`).

Les types permis dépendent de l’offre (403 channel_kind_not_in_plan) : voir Offres et quotas.

Champs communs#

Champ	Sens
`name`	Nom libre, 80 caractères au plus.
`role`	`alerts` (par défaut) ou `escalation` : un canal d’escalade reçoit les rappels des alertes critiques non prises en charge.
`locale`	Langue des messages : `fr` (par défaut) ou `en`.

La configuration d’un canal (URL, jetons, secret) n’est jamais renvoyée par l’API ; le champ target en donne une forme masquée : https://hooks.example.com/aicscan, o***@example.com, Telegram group -1001234567890.

Webhook#

Shell

curl -X POST https://aicscan.io/v1/channels \
  -H "Authorization: Bearer $AICSCAN_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"kind":"webhook","url":"https://hooks.example.com/aicscan","name":"SIEM","locale":"en"}'

La réponse 201 contient webhook_secret (whsec_…), affiché une seule fois : il sert à vérifier les signatures. L’URL doit être en https et désigner un hôte public : les adresses privées, locales, de lien local, de métadonnées cloud ou réservées, les noms locaux et les URL avec identifiants sont refusés (422 url_not_allowed, motif dans details.reason). Le contrôle est refait à chaque envoi.

Discord et Slack#

Shell

curl -X POST https://aicscan.io/v1/channels \
  -H "Authorization: Bearer $AICSCAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"discord","url":"https://discord.com/api/webhooks/1234567890/abcDEF","name":"#treasury"}'

Discord : URL de la forme https://discord.com/api/webhooks/… (Paramètres du salon, Intégrations, Webhooks).
Slack : URL de la forme https://hooks.slack.com/services/… (application Incoming Webhooks).

Email#

Shell

curl -X POST https://aicscan.io/v1/channels \
  -H "Authorization: Bearer $AICSCAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"email","emails":["ops@example.com","cfo@example.com"],"locale":"fr"}'

Telegram et helloMe#

Ces canaux se relient par un lien d’invitation, à ouvrir par un administrateur du groupe dans les 10 minutes. Ils n’acceptent ni name, ni role, ni url, ni emails.

Shell

curl -X POST https://aicscan.io/v1/channels \
  -H "Authorization: Bearer $AICSCAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"telegram","locale":"fr"}'

JSON

{
  "kind": "telegram",
  "status": "pending",
  "invite": {
    "token": "Kx3p9QvT2mWb7aZr",
    "link": "https://t.me/AicscanBot?startgroup=Kx3p9QvT2mWb7aZr",
    "expires_at": "2026-11-14T09:25:00Z",
    "expires_in_minutes": 10
  }
}

Transmettez invite.link à l’administrateur du groupe, puis interrogez l’URL donnée par l’en-tête Location (GET /v1/channel-invites/{token}) jusqu’à status: "linked" : channel_id donne alors l’identifiant du nouveau canal. Une invitation non utilisée passe à expired. Si le service n’a pas de bot configuré pour ce type, la création répond 503 channel_kind_unavailable.

Tester un canal#

Shell

curl -X POST https://aicscan.io/v1/channels/$CHANNEL_ID/test -H "Authorization: Bearer $AICSCAN_API_KEY"

Un message de test part dans la file d’envoi (202) ; son résultat se lit sur GET /v1/notifications/{notification_id} (état et tentatives). Un canal désactivé répond 409 channel_inactive.

Désactiver, réactiver, supprimer#

Shell

curl -X PATCH https://aicscan.io/v1/channels/$CHANNEL_ID \
  -H "Authorization: Bearer $AICSCAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"state":"disabled"}'

curl -X DELETE https://aicscan.io/v1/channels/$CHANNEL_ID -H "Authorization: Bearer $AICSCAN_API_KEY"

PATCH accepte state (active ou disabled) et name. Réactiver un canal remet à zéro sa série d’échecs.
La suppression est logique : l’historique des envois reste lisible et le canal ne compte plus dans l’offre. Elle est refusée tant qu’une règle active utilise le canal (409 channel_in_use, règles dans details.rules) ; les liens avec des règles en pause sont retirés. Les propriétaires de l’espace et ses autres canaux actifs sont prévenus.

Fiabilité des envois#

Chaque envoi est journalisé : GET /v1/notifications/{id} liste les tentatives (delivery_attempts) avec le code HTTP, la durée et l’erreur.
Un envoi en échec est relancé : 30 s, 2 min, 10 min, 30 min, 1 h, 3 h, puis toutes les 6 h, sur 24 heures au plus.
Un canal en échec continu depuis 24 heures est désactivé automatiquement (disabled_reason) et le propriétaire de l’espace est prévenu par email. Réactivez-le par PATCH {"state":"active"} une fois la cause corrigée.
Une notification sent ou failed peut être renvoyée : POST /v1/notifications/{id}/resend.
En cas d’afflux d’alertes, Aicscan regroupe les alertes suivantes dans un récapitulatif envoyé une fois par minute (type: "digest") pour ne pas noyer le canal ; les alertes regroupées ont le statut grouped.