Webhook in entrata

I webhook in entrata permettono a strumenti esterni di pubblicare messaggi automatici in un canale HansaChat. Sono utili per aggiornamenti di deployment, avvisi di monitoraggio, notifiche di ticket, invii di moduli e altri eventi che dovrebbero comparire nella chat di team.

Solo gli amministratori del workspace possono creare e gestire i webhook in entrata.

Creare un webhook

1. Apra Impostazioni dalla barra laterale in basso a sinistra.
2. Selezioni Webhook.
3. Scelga Crea webhook.
4. Inserisca un nome chiaro per il webhook, ad esempio CI Deployments.
5. Scelga il canale in cui devono essere pubblicati i messaggi.
6. Inserisca facoltativamente un URL per l’icona.
7. Scelga Crea webhook.

Copiare l’URL del webhook

Dopo la creazione, HansaChat mostra l’URL del webhook una sola volta. Copi l’URL e lo conservi in modo sicuro nello strumento esterno che invierà gli eventi.

Se chiude questa schermata senza salvare l’URL, ruoti l’URL per generare un nuovo segreto. L’URL precedente smette di funzionare immediatamente dopo la rotazione.

Gestire i webhook

Dalla pagina Webhook, gli amministratori possono:

• Modificare il nome del webhook, il canale, l’URL dell’icona o lo stato attivo.
• Disattivare un webhook per rifiutare i nuovi messaggi senza eliminarlo.
• Ruotare l’URL per invalidare il vecchio segreto e generare un nuovo URL.
• Eliminare un webhook. I messaggi esistenti in chat non vengono rimossi.

Riferimento tecnico

Invii una richiesta POST all’URL del webhook:

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

L’URL identifica il webhook. Ogni consegna deve inoltre essere firmata con il segreto del webhook: invii un’intestazione X-Webhook-Signature contenente un timestamp e una firma HMAC-SHA256 calcolata sul corpo della richiesta. Le consegne non firmate o scadute vengono rifiutate con 401. Conservi l’URL completo in modo segreto.

Firmi le proprie consegne

Ogni richiesta richiede un’intestazione X-Webhook-Signature in questo formato:

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

La firma è un digest HMAC-SHA256 di <timestamp>.<corpo> — il timestamp Unix, un punto e il corpo non elaborato della richiesta — utilizzando come chiave il segreto del webhook dell’URL. Le consegne con un timestamp più vecchio di 5 minuti vengono rifiutate, quindi firmi ogni consegna subito prima di inviarla.

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

Dopo che HansaChat restituisce ok, il messaggio compare nel canale selezionato.

Payload compatibile con Slack

L’endpoint accetta payload JSON compatibili con Slack con text, blocks e 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."
      }
    }
  ]
}

Almeno uno tra text, blocks o attachments deve contenere testo leggibile.

Campi supportati

La dimensione massima del payload è 1 MB.

Limiti di frequenza

L’ingestione dei webhook in entrata è limitata in frequenza per ogni URL di webhook.

Ogni webhook può accettare fino a 10 richieste autenticate al minuto e fino a 100 richieste autenticate all’ora. Quando uno dei due limiti viene raggiunto, HansaChat restituisce 429 resource_exhausted.

Ci contatti se desidera aumentare il limite di frequenza.

I limiti del payload sono applicati separatamente: la dimensione massima del corpo è 1 MB, blocks accetta fino a 50 elementi, attachments accetta fino a 100 elementi e il payload deve contenere testo leggibile.

Idempotenza

Aggiunga un’intestazione Idempotency-Key quando il suo sistema può ritentare lo stesso evento:

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

Se HansaChat riceve di nuovo la stessa chiave di idempotenza per lo stesso webhook, restituisce 200 ok senza creare un messaggio duplicato.

Risposte

Le richieste riuscite restituiscono:

ok

Errori comuni:

Consigli di sicurezza

• Tratti gli URL dei webhook come password.
• Conservi gli URL nel gestore di segreti del suo strumento esterno.
• Firmi ogni consegna con il segreto del webhook — le richieste non firmate vengono rifiutate.
• Ruoti l’URL se è stato esposto o perso.
• Disattivi i webhook inutilizzati.
• Usi un webhook dedicato per ogni sistema esterno, così l’accesso può essere revocato in modo pulito.