Dolazni webhookovi

Dolazni webhookovi omogućuju vanjskim alatima objavljivanje automatskih poruka u HansaChat kanal. Upotrijebite ih za ažuriranja implementacija, upozorenja nadzora, obavijesti o karticama, prijave obrazaca i druge događaje koji trebaju biti vidljivi u timskom chatu.

Samo administratori radnog prostora mogu stvarati i upravljati dolaznim webhookovima.

Stvaranje webhooka

1. Otvorite Postavke iz donje lijeve bočne trake.
2. Odaberite Webhookovi.
3. Odaberite Stvori webhook.
4. Unesite jasan naziv webhooka, primjerice CI Deployments.
5. Odaberite kanal u koji se poruke trebaju objavljivati.
6. Po želji unesite URL ikone.
7. Odaberite Stvori webhook.

Kopiranje URL-a webhooka

Nakon stvaranja HansaChat prikazuje URL webhooka samo jednom. Kopirajte ga i pohranite na sigurno mjesto u vanjskom alatu koji će slati događaje.

Ako zatvorite ovaj zaslon bez spremanja URL-a, rotirajte URL da biste generirali novu tajnu. Prethodni URL prestaje raditi odmah nakon rotacije.

Upravljanje webhookovima

Sa stranice Webhookovi administratori mogu:

• Urediti naziv webhooka, kanal, URL ikone ili aktivno stanje.
• Onemogućiti webhook da biste odbijali nove poruke bez brisanja.
• Rotirati URL da biste poništili staru tajnu i generirali novi URL.
• Izbrisati webhook. Postojeće poruke u chatu ne uklanjaju se.

Tehnička referenca

Pošaljite POST zahtjev na URL webhooka:

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

URL identificira webhook. Svaku isporuku treba dodatno potpisati tajnom webhooka: pošaljite zaglavlje X-Webhook-Signature s vremenskom oznakom i HMAC-SHA256 potpisom izračunatim nad tijelom zahtjeva. Nepotpisane ili istekle isporuke odbijaju se s 401. Čuvajte cijeli URL kao tajnu.

Potpišite svoje isporuke

Svaki zahtjev treba zaglavlje X-Webhook-Signature u ovom formatu:

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

Potpis je HMAC-SHA256 sažetak (digest) nad <vremenska oznaka>.<tijelo> — unix vremenska oznaka, točka i sirovo tijelo zahtjeva — s tajnom webhooka iz URL-a kao ključem. Isporuke s vremenskom oznakom starijom od 5 minuta odbijaju se, stoga potpišite svaku isporuku neposredno prije slanja.

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,
});

Kada HansaChat vrati ok, poruka se pojavljuje u odabranom kanalu.

Payload kompatibilan sa Slackom

Krajnja točka prihvaća JSON payloadove kompatibilne sa Slackom s poljima text, blocks i 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."
      }
    }
  ]
}

Barem jedno od polja text, blocks ili attachments mora sadržavati čitljiv tekst.

Podržana polja

Maksimalna veličina payloada je 1 MB.

Ograničenja učestalosti

Prijem dolaznih webhookova ograničen je po učestalosti za svaki URL webhooka.

Svaki webhook može prihvatiti do 10 autenticiranih zahtjeva u minuti i do 100 autenticiranih zahtjeva na sat. Kada se bilo koje od tih ograničenja dosegne, HansaChat vraća 429 resource_exhausted.

Kontaktirajte nas ako želite povećati ograničenje učestalosti.

Ograničenja payloada provode se odvojeno: maksimalna veličina tijela je 1 MB, blocks prihvaća do 50 stavki, attachments do 100 stavki, a payload mora sadržavati čitljiv tekst.

Idempotencija

Dodajte zaglavlje Idempotency-Key kada vaš sustav može ponovno poslati isti događaj:

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

Ako HansaChat ponovno primi isti ključ idempotencije za isti webhook, vraća 200 ok bez stvaranja duplicirane poruke.

Odgovori

Uspješni zahtjevi vraćaju:

ok

Uobičajene pogreške:

Sigurnosni savjeti

• Postupajte s URL-ovima webhookova kao s lozinkama.
• Pohranite URL-ove u upravitelju tajni svog vanjskog alata.
• Potpišite svaku isporuku tajnom webhooka — nepotpisani zahtjevi odbijaju se.
• Rotirajte URL ako je bio izložen ili izgubljen.
• Onemogućite nekorištene webhookove.
• Upotrijebite namjenski webhook za svaki vanjski sustav kako bi se pristup mogao uredno opozvati.