Prichádzajúce webhooky

Prichádzajúce webhooky umožňujú externým nástrojom odosielať automatizované správy do kanála HansaChat. Použite ich na aktualizácie o nasadeniach, monitorovacie výstrahy, upozornenia na tikety, odoslanie formulárov a ďalšie udalosti, ktoré sa majú zobraziť v tímovom chate.

Prichádzajúce webhooky môžu vytvárať a spravovať iba správcovia workspaceu.

Vytvorenie webhooku

1. Otvorte Nastavenia vľavo dole v bočnom paneli.
2. Vyberte Webhooky.
3. Zvoľte Vytvoriť webhook.
4. Zadajte zrozumiteľný názov webhooku, napríklad CI Deployments.
5. Vyberte kanál, do ktorého sa majú správy odosielať.
6. Voliteľne zadajte URL ikony.
7. Zvoľte Vytvoriť webhook.

Kopírovanie URL webhooku

Po vytvorení HansaChat zobrazí URL webhooku len raz. Skopírujte ju a bezpečne uložte v externom nástroji, ktorý bude odosielať udalosti.

Ak túto obrazovku zatvoríte bez uloženia URL, vygenerujte novú URL, aby vznikol nový tajný kľúč. Predchádzajúca URL po vygenerovaní okamžite prestane fungovať.

Správa webhookov

Na stránke Webhooky môžu správcovia:

• Upraviť názov webhooku, kanál, URL ikony alebo stav aktivity.
• Zakázať webhook, aby odmietal nové správy bez jeho odstránenia.
• Vygenerovať novú URL, čím zneplatníte starý tajný kľúč a vznikne nová URL.
• Odstrániť webhook. Existujúce chatové správy sa neodstránia.

Technická referencia

Na URL webhooku odošlite požiadavku POST:

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

URL identifikuje webhook. Každé doručenie musí byť navyše podpísané tajným kľúčom webhooku: odošlite hlavičku X-Webhook-Signature obsahujúcu časovú pečiatku a podpis HMAC-SHA256 vypočítaný nad telom požiadavky. Nepodpísané alebo vypršané doručenia sú odmietnuté s 401. Celú URL uchovávajte v tajnosti.

Podpísanie doručení

Každá požiadavka potrebuje hlavičku X-Webhook-Signature v tomto formáte:

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

Podpis je digest HMAC-SHA256 nad <časová pečiatka>.<telo> — unixová časová pečiatka, bodka a nespracované telo požiadavky — s tajným kľúčom webhooku z URL ako kľúčom. Doručenia s časovou pečiatkou staršou ako 5 minút sú odmietnuté, preto každé doručenie podpíste tesne pred odoslaní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,
});

Keď HansaChat vráti ok, správa sa zobrazí vo vybratom kanáli.

Payload kompatibilný so Slackom

Koncový bod prijíma payloady JSON kompatibilné so Slackom s poliami 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."
      }
    }
  ]
}

Aspoň jedno z polí text, blocks alebo attachments musí obsahovať čitateľný text.

Podporované polia

Maximálna veľkosť payloadu je 1 MB.

Obmedzenie frekvencie

Príjem prichádzajúcich webhookov je obmedzený na počet požiadaviek pripadajúcich na jednu URL webhooku.

Každý webhook môže prijať najviac 10 overených požiadaviek za minútu a najviac 100 overených požiadaviek za hodinu. Po dosiahnutí ktoréhokoľvek z týchto limitov HansaChat vráti 429 resource_exhausted.

Ak chcete obmedzenie frekvencie zvýšiť, kontaktujte nás.

Limity payloadu sa vynucujú osobitne: maximálna veľkosť tela požiadavky je 1 MB, pole blocks prijíma najviac 50 položiek, pole attachments najviac 100 položiek a payload musí obsahovať čitateľný text.

Idempotentnosť

Keď môže váš systém tú istú udalosť odoslať opakovane, pridajte 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"}'

Ak HansaChat prijme rovnaký idempotentný kľúč znova pre ten istý webhook, vráti 200 ok bez vytvorenia duplicitnej správy.

Odpovede

Úspešné požiadavky vracajú:

ok

Bežné chyby:

Bezpečnostné tipy

• Zaobchádzajte s URL webhookov ako s heslami.
• Ukladajte URL do správcu tajomstiev vášho externého nástroja.
• Každé doručenie podpíste tajným kľúčom webhooku — nepodpísané požiadavky sú odmietnuté.
• Vygenerujte novú URL, ak bola prezradená alebo stratená.
• Nepoužívané webhooky zakážte.
• Pre každý externý systém použite samostatný webhook, aby bolo možné prístup čisto odvolať.