Příchozí webhooky

Příchozí webhooky umožňují externím nástrojům posílat automatizované zprávy do kanálu HansaChat. Použijte je pro aktualizace o nasazeních, výstrahy monitoringu, upozornění na tikety, odeslané formuláře a další události, které se mají objevit v týmovém chatu.

Příchozí webhooky můžou vytvářet a spravovat pouze správci workspace.

Vytvoření webhooku

1. Otevřete Nastavení v postranní liště vlevo dole.
2. Zvolte Webhooky.
3. Zvolte Vytvořit webhook.
4. Zadejte výstižný název webhooku, například CI Deployments.
5. Zvolte kanál, do kterého se mají zprávy posílat.
6. Volitelně zadejte URL ikony.
7. Zvolte Vytvořit webhook.

Zkopírování URL webhooku

Po vytvoření zobrazí HansaChat URL webhooku pouze jednou. Zkopírujte jej a bezpečně uložte v externím nástroji, který má události odesílat.

Pokud tuto obrazovku zavřete bez uložení URL, obměňte URL, abyste vygenerovali nové tajemství. Předchozí URL po obměně okamžitě přestane fungovat.

Správa webhooků

Ze stránky Webhooky můžou správci:

• Upravit název webhooku, kanál, URL ikony nebo stav aktivace.
• Zakázat webhook, aby odmítl nové zprávy, aniž by byl smazán.
• Obměnit URL — tím zneplatníte staré tajemství a vygenerujete nové URL.
• Smazat webhook. Existující zprávy v chatu se nemažou.

Technická reference

Odešlete na URL webhooku požadavek POST:

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

URL identifikuje webhook. Každé doručení musí být navíc podepsáno tajemstvím webhooku: odešlete hlavičku X-Webhook-Signature obsahující časové razítko a podpis HMAC-SHA256 vypočtený nad tělem požadavku. Nepodepsaná nebo vypršelá doručení jsou zamítnuta s 401. Celé URL uchovávejte v tajnosti.

Podepisování doručení

Každý požadavek potřebuje hlavičku X-Webhook-Signature v tomto formátu:

t=<unix timestamp>,v1=<hex signature>

Podpis je digest HMAC-SHA256 nad <časové razítko>.<tělo> — unixovské časové razítko, tečka a surové tělo požadavku — klíčovaný tajemstvím webhooku z URL. Doručení s časovým razítkem starším než 5 minut jsou zamítnuta, proto každé doručení podepište těsně před odesláním.

Bash (openssl):

URL='https://{workspace-domain}/api/webhooks/{publicID}/{secret}'
BODY='{"text":"Deployment completed successfully"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | \
  openssl dgst -sha256 -hmac "$(basename "$URL")" | awk '{print $NF}')
curl -X POST "$URL" \
  -H 'Content-Type: application/json' \
  -H "X-Webhook-Signature: t=$TS,v1=$SIG" \
  -d "$BODY"

Python:

import hashlib, hmac, time, requests

url = "https://{workspace-domain}/api/webhooks/{publicID}/{secret}"
secret = url.rsplit("/", 1)[-1]
body = b'{"text":"Deployment completed successfully"}'
ts = str(int(time.time()))
sig = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
requests.post(url, data=body,
              headers={"Content-Type": "application/json",
                       "X-Webhook-Signature": f"t={ts},v1={sig}"})

Node.js:

import { createHmac } from "node:crypto";

const url = "https://{workspace-domain}/api/webhooks/{publicID}/{secret}";
const secret = new URL(url).pathname.split("/").at(-1);
const body = JSON.stringify({ text: "Deployment completed successfully" });
const ts = Math.floor(Date.now() / 1000);
const sig = createHmac("sha256", secret).update(`${ts}.${body}`).digest("hex");
await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Webhook-Signature": `t=${ts},v1=${sig}`,
  },
  body,
});

Jakmile HansaChat vrátí ok, zpráva se objeví ve vybraném kanále.

Payload kompatibilní se Slackem

Endpoint přijímá payloady JSON kompatibilní se Slackem s poli text, blocks a 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."
      }
    }
  ]
}

Nejméně jedno z polí text, blocks nebo attachments musí obsahovat čitelný text.

Podporovaná pole

Maximální velikost payloadu je 1 MB.

Limity rychlosti

Příjem přes příchozí webhooky je omezen na rychlost pro každou URL webhooku zvlášť.

Každý webhook přijme až 10 autentizovaných požadavků za minutu a až 100 autentizovaných požadavků za hodinu. Po dosažení kteréhokoli limitu vrátí HansaChat 429 resource_exhausted.

Chcete-li limit rychlosti zvýšit, kontaktujte nás.

Limity payloadu se vynucují zvlášť: maximální velikost těla je 1 MB, pole blocks přijímá až 50 položek, pole attachments až 100 položek a payload musí obsahovat čitelný text.

Idempotence

Pokud váš systém může stejnou událost opakovat, přidejte hlavičku Idempotency-Key:

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"}'

Pokud HansaChat pro stejný webhook obdrží stejný klíč idempotence znovu, vrátí 200 ok bez vytvoření duplicitní zprávy.

Odpovědi

Úspěšné požadavky vracejí:

ok

Běžné chyby:

Bezpečnostní tipy

• Zacházejte s URL webhooků jako s hesly.
• Ukládejte URL do správce tajemství vašeho externího nástroje.
• Každé doručení podepište tajemstvím webhooku — nepodepsané požadavky jsou zamítnuty.
• Obměňte URL, pokud uniklo nebo se ztratilo.
• Zakazujte nepoužívané webhooky.
• Pro každý externí systém použijte samostatný webhook, aby šlo přístup čistě odvolat.