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 obsahuje prihlasovacie údaje webhooku. Nie je potrebná žiadna ďalšia hlavička overenia. Celú URL uchovávajte v tajnosti.

Minimálna požiadavka

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

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.
• 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ť.