Inkommande webhooks

Inkommande webhooks låter externa verktyg posta automatiserade meddelanden i en HansaChat-kanal. Använd dem för driftsättningsuppdateringar, övervakningslarm, ärendenotiser, formulärsvar och andra händelser som bör synas i teamchatten.

Endast arbetsytans administratörer kan skapa och hantera inkommande webhooks.

Skapa en webhook

1. Öppna Inställningar från sidopanelens nedre vänstra hörn.
2. Välj Webhooks.
3. Välj Skapa webhook.
4. Ange ett tydligt webhook-namn, till exempel CI Deployments.
5. Välj kanalen som meddelandena ska postas i.
6. Ange vid behov en ikon-URL.
7. Välj Skapa webhook.

Kopiera webhook-URL:en

Efter skapandet visar HansaChat webhook-URL:en en enda gång. Kopiera den och spara den på ett säkert ställe i det externa verktyg som ska skicka händelser.

Stänger ni den här vyn utan att ha sparat URL:en roterar ni URL:en för att skapa en ny hemlighet. Den tidigare URL:en slutar fungera omedelbart efter rotationen.

Hantera webhooks

På webhooksidan kan administratörer:

• Redigera webhookens namn, kanal, ikon-URL eller aktiva tillstånd.
• Inaktivera en webhook för att avvisa nya meddelanden utan att radera den.
• Rotera URL för att ogiltigförklara den gamla hemligheten och skapa en ny URL.
• Radera en webhook. Befintliga chattmeddelanden tas inte bort.

Teknisk referens

Skicka en POST-begäran till webhook-URL:en:

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

URL:en identifierar webhooken. Varje leverans måste dessutom signeras med webhookens hemlighet: skicka en X-Webhook-Signature-header med en tidsstämpel och en HMAC-SHA256-signatur beräknad över begärans brödtext. Osignerade eller utgångna leveranser avvisas med 401. Håll hela URL:en hemlig.

Signera era leveranser

Varje begäran behöver en X-Webhook-Signature-header i följande format:

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

Signaturen är en HMAC-SHA256-digest över <tidsstämpel>.<brödtext> — unix-tidsstämpeln, en punkt och begärans råa brödtext — med webhookens hemlighet från URL:en som nyckel. Leveranser med en tidsstämpel äldre än 5 minuter avvisas, så signera varje leverans direkt innan den skickas.

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 har returnerat ok visas meddelandet i den valda kanalen.

Slack-kompatibel nyttolast

Slutpunkten accepterar Slack-kompatibla JSON-nyttolaster med text, blocks och 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."
      }
    }
  ]
}

Minst ett av text, blocks eller attachments måste innehålla läsbar text.

Fält som stöds

Största nyttolaststorlek är 1 MB.

Hastighetsbegränsningar

Inkommande webhooks är hastighetsbegränsade per webhook-URL.

Varje webhook kan ta emot upp till 10 autentiserade begäranden per minut och upp till 100 autentiserade begäranden per timme. När någon av gränserna nås returnerar HansaChat 429 resource_exhausted.

Kontakta oss om ni vill höja hastighetsbegränsningen.

Nyttolastgränserna hanteras separat: största brödtext är 1 MB, blocks tar upp till 50 objekt, attachments tar upp till 100 objekt, och nyttolasten måste innehålla läsbar text.

Idempotens

Lägg till en Idempotency-Key-header när ert system kan skicka om samma händelse:

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

Får HansaChat samma idempotensnyckel igen för samma webhook returneras 200 ok utan att något dubblettmeddelande skapas.

Svar

Lyckade begäranden returnerar:

ok

Vanliga fel:

Säkerhetstips

• Behandla webhook-URL:er som lösenord.
• Spara URL:erna i det externa verktygets hemlighetshanterare.
• Signera varje leverans med webhookens hemlighet — osignerade begäranden avvisas.
• Rotera URL:en om den har exponerats eller kommit bort.
• Inaktivera oanvända webhooks.
• Använd en dedikerad webhook per externt system så att åtkomsten kan återkallas rent.