Ienākošie webhooki

Ienākošie webhooki ļauj ārējiem rīkiem ievietot automātiskus ziņojumus HansaChat kanālā. Izmantojiet tos izvietošanas atjauninājumiem, uzraudzības brīdinājumiem, biļešu paziņojumiem, formu iesniegumiem un citiem notikumiem, kuriem jāparādās komandas tērzēšanā.

Ienākošos webhookus var izveidot un pārvaldīt tikai darbavietu administratori.

Izveidojiet webhooku

1. Atveriet Iestatījumi no apakšējās kreisās sānu joslas daļas.
2. Atlasiet Webhooki.
3. Izvēlieties Izveidot webhooku.
4. Ievadiet skaidru webhooka nosaukumu, piemēram, CI Deployments.
5. Izvēlieties kanālu, kurā ziņojumi jāpublicē.
6. Neobligāti ievadiet ikonas URL.
7. Izvēlieties Izveidot webhooku.

Nokopējiet webhooka URL

Pēc izveides HansaChat parāda webhooka URL tikai vienreiz. Nokopējiet to un uzglabājiet drošībā ārējā rīkā, kas sūtīs notikumus.

Ja aizverat šo ekrānu, nesaglabājot URL, nomainiet URL, lai ģenerētu jaunu slepeno atslēgu. Iepriekšējais URL pārstāj darboties uzreiz pēc nomaiņas.

Pārvaldiet webhookus

No webhooku lapas administratori var:

• Rediģēt webhooka nosaukumu, kanālu, ikonas URL vai aktīvo stāvokli.
• Atspējot webhooku, lai noraidītu jaunus ziņojumus, to nedzēšot.
• Nomainīt URL, lai atspēkotu veco slepeno atslēgu un ģenerētu jaunu URL.
• Dzēst webhooku. Esošie tērzēšanas ziņojumi netiek noņemti.

Tehniskā atsauce

Nosūtiet POST pieprasījumu uz webhooka URL:

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

URL identificē webhooku. Katru piegādi nepieciešams papildu parakstīt ar webhooka slepeno atslēgu: nosūtiet galveni X-Webhook-Signature ar laika zīmogu un HMAC-SHA256 parakstu, kas aprēķināts pār pieprasījuma pamattekstu. Neparakstītas vai beigušās piegādes tiek noraidītas ar 401. Turiet pilnu URL slepenībā.

Parakstiet savas piegādes

Katram pieprasījumam nepieciešama galvene X-Webhook-Signature šādā formātā:

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

Paraksts ir HMAC-SHA256 kontrolsumma (digest), kas aprēķināta pār <laika zīmogs>.<pamatteksts> — unix laika zīmogs, punkts un pieprasījuma neapstrādātais pamatteksts —, izmantojot kā atslēgu webhooka slepeno atslēgu no URL. Piegādes ar laika zīmogu, kas vecāks par 5 minūtēm, tiek noraidītas, tāpēc parakstiet katru piegādi tieši pirms nosūtīšanas.

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

Kad HansaChat atgriež ok, ziņojums parādās izvēlētajā kanālā.

Ar Slack saderīgs payload

Galapunkts pieņem ar Slack saderīgas JSON slodzes ar text, blocks un 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."
      }
    }
  ]
}

Kaut vienam no text, blocks vai attachments jāsatur salasāms teksts.

Atbalstītie lauki

Maksimālais payload izmērs ir 1 MB.

Pieprasījumu ierobežojumi

Ienākošo webhooku uzņemšana ir ierobežota katram webhooka URL atsevišķi.

Katrs webhooks var pieņemt līdz 10 autentificētiem pieprasījumiem minūtē un līdz 100 autentificētiem pieprasījumiem stundā. Kad kāds no ierobežojumiem ir sasniegts, HansaChat atgriež 429 resource_exhausted.

Lūdzu, sazinieties ar mums, ja vēlaties paaugstināt pieprasījumu ierobežojumu.

Payload ierobežojumi tiek piemēroti atsevišķi: maksimālais pamatteksta izmērs ir 1 MB, blocks pieņem līdz 50 vienībām, attachments pieņem līdz 100 vienībām, un payload jāsatur salasāms teksts.

Idempotence

Pievienojiet Idempotency-Key galveni, kad jūsu sistēma var atkārtoti nosūtīt vienu un to pašu notikumu:

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

Ja HansaChat vienam un tam pašam webhookam atkārtoti saņem vienu un to pašu idempotences atslēgu, tas atgriež 200 ok, neizveidojot dublētu ziņojumu.

Atbildes

Veiksmīgi pieprasījumi atgriež:

ok

Biežākās kļūdas:

Drošības ieteikumi

• Ar webhooku URL rīkojieties kā ar parolēm.
• Uzglabājiet URL savas ārējās sistēmas slepeno datu pārvaldniekā.
• Parakstiet katru piegādi ar webhooka slepeno atslēgu — neparakstīti pieprasījumi tiek noraidīti.
• Nomainiet URL, ja tas tika atklāts vai pazuda.
• Atspējojiet nelietotos webhookus.
• Katrai ārējai sistēmai izmantojiet atsevišķu webhooku, lai piekļuvi varētu tīri atsaukt.