Docs › Webhooks

Webhooks entrants

Disponible · gratuit

Une adresse secrète par canal. Tout ce qui y est posté devient un message, au nom de l'intégration.

Créer l'adresse

Administration › Intégrations, puis « Nouveau webhook entrant ». Réservé aux propriétaires et aux admins.
Donne un nom et un avatar, choisis un canal. Un canal confidentiel ne peut pas en recevoir.
Copie l'adresse, https://integrations.mysynkro.fr/hooks/in/syk_whk_… : elle ne s'affiche qu'une fois et suffit pour publier, garde-la comme un mot de passe. Si elle fuite, « Renouveler l'adresse » : l'ancienne répond 404 tout de suite.

Format Synkro

Le format Synkro s'envoie à l'adresse telle quelle :

POST /hooks/in/<jeton>

curl -X POST "https://integrations.mysynkro.fr/hooks/in/syk_whk_…" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Le déploiement de **api-client** a échoué.",
    "title": "Déploiement",
    "title_url": "https://ci.exemple.fr/42",
    "fields": [{ "name": "Branche", "value": "main" }],
    "footer": "CI"
  }'

Au moins text ou title. Le texte est du Markdown de Synkro ; les champs inconnus sont ignorés ; 10 champs fields au plus. Ajoute ?wait=true pour recevoir { "message_id": "…", "url": "…" }. Les mentions s'écrivent <@id> avec l'identifiant d'une personne visible dans le canal ; @canal n'est jamais interprété.

Format Slack

Le format Slack s'envoie à la même adresse suivie de /slack. Synkro convertit les champs text, attachments et blocks en Markdown (gras, italique, liens, code) et ignore le reste (username, icon_url, channel…). Le format Slack ne crée jamais de mention, et @channel et @here restent du texte, sans notification. Beaucoup d'outils d'alerte savent déjà l'émettre : il suffit de coller l'adresse.

Signer les requêtes (facultatif)

Un administrateur peut exiger une signature : Synkro crée alors un secret whsec_…, affiché une seule fois. L'émetteur envoie X-Synkro-Timestamp (secondes Unix) et X-Synkro-Signature: v1=<hex>, où l'empreinte est le HMAC-SHA256 en hexadécimal de <horodatage>.<corps brut> avec le secret. Un horodatage à plus de 5 minutes de l'heure du serveur est refusé, et une requête sans signature aussi (401).

BODY='{"text":"Déploiement terminé"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SYNKRO_WEBHOOK_SECRET" | sed 's/^.* //')
curl -X POST "$SYNKRO_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-Synkro-Timestamp: $TS" \
  -H "X-Synkro-Signature: v1=$SIG" \
  -d "$BODY"

Sans connecteur Synkro (les connecteurs n8n et Make sont en développement), leurs modules génériques suffisent : dans une étape de GitHub Actions, ce script va dans un run:, avec l'adresse et le secret lus depuis les secrets du dépôt. Dans n8n, calcule l'empreinte dans un nœud « Crypto » (HMAC, SHA-256, sortie hexadécimale) puis envoie les deux en-têtes depuis un nœud « HTTP Request ». Dans Make, utilise la fonction sha256(texte; hex; secret) dans un module « HTTP › Make a request ». Dans les trois cas, signe exactement les octets que tu envoies.

Réponses et limites

Code	Corps	Quand
200	`ok`	Message publié.
400	`invalid_payload`, `no_text`	JSON invalide, ou rien à afficher.
401	`invalid_signature`	Signature absente ou fausse.
403	`channel_is_archived`, `org_read_only`	Canal archivé, ou organisation en lecture seule.
404	`no_service`	Adresse inconnue, renouvelée ou désactivée.
413	`payload_too_large`	Corps de plus de 100 Kio.
429	`rate_limited`	Trop d'envois : réessaie après `Retry-After`.

Corps de 100 Kio au plus. Aucun en-tête CORS.
Par webhook : 10 messages d'un coup, puis 1 par seconde. Au-delà, 429 avec Retry-After. Par organisation : 300 messages par minute.
Synkro note l'heure, le statut, la taille et le format des 50 derniers appels (7 jours au plus), jamais leur contenu.