Indgående webhooks

Indgående webhooks lader eksterne værktøjer sende automatiserede beskeder til en HansaChat-kanal. Brug dem til deploy-opdateringer, overvågningsalarmer, ticket-notifikationer, formularindsendelser og andre hændelser, der skal vises i teamchatten.

Kun workspace-administratorer kan oprette og administrere indgående webhooks.

Opret en webhook

1. Åbn Indstillinger i sidebjælken nederst til venstre.
2. Vælg Webhooks.
3. Vælg Opret webhook.
4. Indtast et tydeligt webhook-navn, f.eks. CI Deployments.
5. Vælg den kanal, hvor beskederne skal postes.
6. Indtast evt. en ikon-URL.
7. Vælg Opret webhook.

Kopiér webhook-URL'en

Efter oprettelsen viser HansaChat webhook-URL'en én gang. Kopiér den, og gem den sikkert i det eksterne værktøj, der skal sende hændelser.

Hvis De lukker denne skærm uden at gemme URL'en, skal De rotere URL'en for at generere en ny hemmelig nøgle. Den forrige URL holder op med at virke straks efter rotationen.

Administrér webhooks

Fra Webhooks-siden kan administratorer:

• Redigér webhookens navn, kanal, ikon-URL eller aktive tilstand.
• Deaktivér en webhook for at afvise nye beskeder uden at slette den.
• Rotér URL for at ugyldiggøre den gamle hemmelige nøgle og generere en ny URL.
• Slet en webhook. Eksisterende chatbeskeder fjernes ikke.

Teknisk reference

Send en POST-anmodning til webhook-URL'en:

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

URL'en identificerer webhooken. Hver levering skal også signeres med webhookens hemmelige nøgle: send en X-Webhook-Signature-header med et tidsstempel og en HMAC-SHA256-signatur beregnet over anmodningens brødtekst. Usignerede eller udløbne leveringer afvises med 401. Hold hele URL'en hemmelig.

Signér leveringerne

Hver anmodning kræver en X-Webhook-Signature-header i dette format:

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

Signaturen er en HMAC-SHA256-digest over <tidsstempel>.<brødtekst> — unix-tidsstemplet, et punktum og anmodningens rå brødtekst — med webhookens hemmelige nøgle fra URL'en som nøgle. Leveringer med et tidsstempel ældre end 5 minutter afvises, så signér hver levering lige inden afsendelsen.

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

Når HansaChat returnerer ok, vises beskeden i den valgte kanal.

Slack-kompatibel payload

Endpointet accepterer Slack-kompatible JSON-payloads med text, blocks og 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."
      }
    }
  ]
}

Mindst én af text, blocks eller attachments skal indeholde læsbar tekst.

Understøttede felter

Maksimal payload-størrelse er 1 MB.

Rate-grænser

Indtagelsen af indgående webhooks er rate-begrænset pr. webhook-URL.

Hver webhook kan acceptere op til 10 godkendte anmodninger i minuttet og op til 100 godkendte anmodninger i timen. Når en af grænserne nås, returnerer HansaChat 429 resource_exhausted.

Kontakt os, hvis De ønsker at få hævet rate-grænsen.

Payload-grænserne håndhæves separat: maksimal brødtekststørrelse er 1 MB, blocks accepterer op til 50 elementer, attachments accepterer op til 100 elementer, og payloaden skal indeholde læsbar tekst.

Idempotens

Tilføj en Idempotency-Key-header, når Deres system muligvis sender den samme hændelse igen:

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

Hvis HansaChat modtager den samme idempotensnøgle igen for den samme webhook, returneres 200 ok uden at der oprettes en duplikeret besked.

Svar

Vellykkede anmodninger returnerer:

ok

Almindelige fejl:

Sikkerhedstips

• Behandl webhook-URL'er som adgangskoder.
• Gem URL'erne i Deres eksterne værktøjs secret manager.
• Signér hver levering med webhookens hemmelige nøgle — usignerede anmodninger afvises.
• Rotér URL'en, hvis den er blevet eksponeret eller mistet.
• Deaktivér ubrugte webhooks.
• Brug én dedikeret webhook pr. eksternt system, så adgangen kan tilbagekaldes på en ren måde.