Webhook-uri primite

Webhook-urile primite le permit instrumentelor externe să publice mesaje automate într-un canal HansaChat. Utilizați-le pentru actualizări de implementare, alerte de monitorizare, notificări de tichete, trimiteri de formulare și alte evenimente care ar trebui să apară în chat-ul echipei.

Doar administratorii de workspace pot crea și gestiona webhook-uri primite.

Creați un webhook

1. Deschideți Setări din bara laterală din stânga jos.
2. Selectați Webhook-uri.
3. Alegeți Creare webhook.
4. Introduceți un nume clar de webhook, cum ar fi CI Deployments.
5. Alegeți canalul în care ar trebui publicate mesajele.
6. Opțional, introduceți un URL de pictogramă.
7. Alegeți Creare webhook.

Copiați URL-ul webhook-ului

După creare, HansaChat afișează URL-ul webhook-ului o singură dată. Copiați-l și stocați-l în condiții de siguranță în instrumentul extern care va trimite evenimentele.

Dacă închideți acest ecran fără a salva URL-ul, regenerați URL-ul pentru a produce un nou secret. URL-ul anterior încetează să funcționeze imediat după regenerare.

Gestionați webhook-urile

Din pagina Webhook-uri, administratorii pot:

• Edita numele webhook-ului, canalul, URL-ul pictogramei sau starea activă.
• Dezactiva un webhook pentru a respinge mesajele noi fără a-l șterge.
• Regenerare URL pentru a invalida vechiul secret și a genera un URL nou.
• Șterge un webhook. Mesajele existente din chat nu sunt eliminate.

Referință tehnică

Trimiteți o cerere POST către URL-ul webhook-ului:

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

URL-ul conține datele de autentificare ale webhook-ului. Nu este necesar niciun antet suplimentar de autentificare. Păstrați URL-ul complet secret.

Cerere minimă

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

După ce HansaChat returnează ok, mesajul apare în canalul selectat.

Payload compatibil cu Slack

Punctul final acceptă payload-uri JSON compatibile cu Slack, cu text, blocks și 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."
      }
    }
  ]
}

Cel puțin unul dintre text, blocks sau attachments trebuie să conțină text lizibil.

Câmpuri acceptate

Dimensiunea maximă a payload-ului este de 1 MB.

Limite de rată

Ingestia webhook-urilor primite este limitată ca rată per URL de webhook.

Fiecare webhook poate accepta până la 10 cereri autenticate pe minut și până la 100 de cereri autenticate pe oră. Când una dintre limite este atinsă, HansaChat returnează 429 resource_exhausted.

Vă rugăm să ne contactați dacă doriți să creșteți limita de rată.

Limitele pentru payload sunt impuse separat: dimensiunea maximă a corpului este de 1 MB, blocks acceptă până la 50 de elemente, attachments acceptă până la 100 de elemente, iar payload-ul trebuie să conțină text lizibil.

Idempotență

Adăugați un antet Idempotency-Key atunci când sistemul dvs. poate reîncerca același eveniment:

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

Dacă HansaChat primește din nou aceeași cheie de idempotență pentru același webhook, returnează 200 ok fără a crea un mesaj duplicat.

Răspunsuri

Cererile reușite returnează:

ok

Erori obișnuite:

Sfaturi de securitate

• Tratați URL-urile de webhook ca pe parole.
• Stocați URL-urile în managerul de secrete al instrumentului extern.
• Regenerați URL-ul dacă acesta a fost expus sau pierdut.
• Dezactivați webhook-urile nefolosite.
• Utilizați un webhook dedicat pentru fiecare sistem extern, astfel încât accesul să poată fi revocat în mod curat.