Webhook-uri primite

Webhook-urile primite le permit instrumentelor externe să publice mesaje automate într-un canal HansaChat. Utilizați-le pentru actualizări de implementare, alerte de monitorizare, notificări de tichete, trimiteri de formulare și alte evenimente care ar trebui să apară în chat-ul echipei.

Doar administratorii de workspace pot crea și gestiona webhook-uri primite.

Creați un webhook

1. Deschideți Setări din bara laterală din stânga jos.
2. Selectați Webhook-uri.
3. Alegeți Creare webhook.
4. Introduceți un nume clar de webhook, cum ar fi CI Deployments.
5. Alegeți canalul în care ar trebui publicate mesajele.
6. Opțional, introduceți un URL de pictogramă.
7. Alegeți Creare webhook.

Copiați URL-ul webhook-ului

După creare, HansaChat afișează URL-ul webhook-ului o singură dată. Copiați-l și stocați-l în condiții de siguranță în instrumentul extern care va trimite evenimentele.

Dacă închideți acest ecran fără a salva URL-ul, regenerați URL-ul pentru a produce un nou secret. URL-ul anterior încetează să funcționeze imediat după regenerare.

Gestionați webhook-urile

Din pagina Webhook-uri, administratorii pot:

• Edita numele webhook-ului, canalul, URL-ul pictogramei sau starea activă.
• Dezactiva un webhook pentru a respinge mesajele noi fără a-l șterge.
• Regenerare URL pentru a invalida vechiul secret și a genera un URL nou.
• Șterge un webhook. Mesajele existente din chat nu sunt eliminate.

Referință tehnică

Trimiteți o cerere POST către URL-ul webhook-ului:

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

URL-ul identifică webhook-ul. Fiecare livrare trebuie să fie semnată în plus cu secretul webhook-ului: trimiteți un antet X-Webhook-Signature care conține un timestamp și o semnătură HMAC-SHA256 calculată pe corpul cererii. Livrările nesemnate sau expirate sunt respinse cu 401. Păstrați URL-ul complet secret.

Semnați livrările

Fiecare cerere are nevoie de un antet X-Webhook-Signature în acest format:

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

Semnătura este un digest HMAC-SHA256 calculat pe <timestamp>.<corp> — timestamp-ul Unix, un punct și corpul brut al cererii — utilizând ca cheie secretul webhook-ului din URL. Livrările cu un timestamp mai vechi de 5 minute sunt respinse, așa că semnați fiecare livrare chiar înainte de a o trimite.

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

După ce HansaChat returnează ok, mesajul apare în canalul selectat.

Payload compatibil cu Slack

Punctul final acceptă payload-uri JSON compatibile cu Slack, cu 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."
      }
    }
  ]
}

Cel puțin unul dintre text, blocks sau attachments trebuie să conțină text lizibil.

Câmpuri acceptate

Dimensiunea maximă a payload-ului este de 1 MB.

Limite de rată

Ingestia webhook-urilor primite este limitată ca rată per URL de webhook.

Fiecare webhook poate accepta până la 10 cereri autenticate pe minut și până la 100 de cereri autenticate pe oră. Când una dintre limite este atinsă, HansaChat returnează 429 resource_exhausted.

Vă rugăm să ne contactați dacă doriți să creșteți limita de rată.

Limitele pentru payload sunt impuse separat: dimensiunea maximă a corpului este de 1 MB, blocks acceptă până la 50 de elemente, attachments acceptă până la 100 de elemente, iar payload-ul trebuie să conțină text lizibil.

Idempotență

Adăugați un antet Idempotency-Key atunci când sistemul dvs. poate reîncerca același eveniment:

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

Dacă HansaChat primește din nou aceeași cheie de idempotență pentru același webhook, returnează 200 ok fără a crea un mesaj duplicat.

Răspunsuri

Cererile reușite returnează:

ok

Erori obișnuite:

Sfaturi de securitate

• Tratați URL-urile de webhook ca pe parole.
• Stocați URL-urile în managerul de secrete al instrumentului extern.
• Semnați fiecare livrare cu secretul webhook-ului — cererile nesemnate sunt respinse.
• Regenerați URL-ul dacă acesta a fost expus sau pierdut.
• Dezactivați webhook-urile nefolosite.
• Utilizați un webhook dedicat pentru fiecare sistem extern, astfel încât accesul să poată fi revocat în mod curat.