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 contiene le credenziali del webhook. Non è richiesta alcuna intestazione di autenticazione aggiuntiva. Conservi l’URL completo in modo segreto.

Richiesta minima

curl -X POST 'https://{workspace-domain}/api/webhooks/{publicID}/{secret}' \
  -H 'Content-Type: application/json' \
  -d '{"text":"Deployment completed successfully"}'

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.
• 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.