Webhooks entrants

Les webhooks entrants permettent aux outils externes de publier des messages automatisés dans un canal HansaChat. Utilisez-les pour les mises à jour de déploiement, les alertes de surveillance, les notifications de tickets, les soumissions de formulaires et tout autre événement qui doit apparaître dans la discussion d’équipe.

Seuls les administrateurs de l’espace de travail peuvent créer et gérer des webhooks entrants.

Créer un webhook

1. Ouvrez Paramètres depuis le bas de la barre latérale, à gauche.
2. Sélectionnez Webhooks.
3. Choisissez Créer un webhook.
4. Saisissez un nom de webhook clair, par exemple Déploiements CI.
5. Choisissez le canal dans lequel les messages doivent être publiés.
6. Saisissez éventuellement une URL d’icône.
7. Choisissez Créer un webhook.

Copier l’URL du webhook

Après la création, HansaChat affiche l’URL du webhook une seule fois. Copiez-la et conservez-la en lieu sûr dans l’outil externe qui enverra les événements.

Si vous fermez cet écran sans avoir enregistré l’URL, régénérez l’URL pour produire un nouveau secret. L’URL précédente cesse de fonctionner immédiatement après la régénération.

Gérer les webhooks

Depuis la page Webhooks, les administrateurs peuvent :

• Modifier le nom du webhook, le canal, l’URL d’icône ou l’état actif.
• Désactiver un webhook pour rejeter les nouveaux messages sans le supprimer.
• Régénérer l’URL pour invalider l’ancien secret et générer une nouvelle URL.
• Supprimer un webhook. Les messages de discussion existants ne sont pas retirés.

Référence technique

Envoyez une requête POST à l’URL du webhook :

https://{workspace-domain}/api/webhooks/{publicID}/{secret}

L’URL contient les identifiants du webhook. Aucun en-tête d’authentification supplémentaire n’est requis. Gardez l’URL complète secrète.

Requête minimale

curl -X POST 'https://{workspace-domain}/api/webhooks/{publicID}/{secret}' \
  -H 'Content-Type: application/json' \
  -d '{"text":"Deployment completed successfully"}'

Une fois que HansaChat renvoie ok, le message apparaît dans le canal sélectionné.

Payload compatible Slack

Le point de terminaison accepte des payloads JSON compatibles Slack avec text, blocks et attachments.

{
  "text": "Deployment completed successfully",
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "Deployment completed"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Branch `main` is now live."
      }
    }
  ]
}

Au moins l’un des champs text, blocks ou attachments doit contenir du texte lisible.

Champs pris en charge

La taille maximale du payload est de 1 Mo.

Limites de débit

L’ingestion des webhooks entrants est soumise à une limite de débit par URL de webhook.

Chaque webhook peut accepter jusqu’à 10 requêtes authentifiées par minute et jusqu’à 100 requêtes authentifiées par heure. Lorsque l’une de ces limites est atteinte, HansaChat renvoie 429 resource_exhausted.

Contactez-nous si vous souhaitez augmenter la limite de débit.

Les limites de payload sont appliquées séparément : la taille maximale du corps est de 1 Mo, blocks accepte jusqu’à 50 éléments, attachments accepte jusqu’à 100 éléments, et le payload doit contenir du texte lisible.

Idempotence

Ajoutez un en-tête Idempotency-Key lorsque votre système peut réessayer le même événement :

curl -X POST 'https://{workspace-domain}/api/webhooks/{publicID}/{secret}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: deploy-1247' \
  -d '{"text":"Deployment #1247 completed"}'

Si HansaChat reçoit à nouveau la même clé d’idempotence pour le même webhook, il renvoie 200 ok sans créer de message en double.

Réponses

Les requêtes réussies renvoient :

ok

Erreurs courantes :

Conseils de sécurité

• Traitez les URL de webhook comme des mots de passe.
• Conservez les URL dans le gestionnaire de secrets de votre outil externe.
• Régénérez l’URL si elle a été exposée ou perdue.
• Désactivez les webhooks inutilisés.
• Utilisez un webhook dédié par système externe afin que l’accès puisse être révoqué proprement.