Εισερχόμενα webhooks

Τα εισερχόμενα webhooks επιτρέπουν σε εξωτερικά εργαλεία να δημοσιεύουν αυτοματοποιημένα μηνύματα σε ένα κανάλι του HansaChat. Χρησιμοποιήστε τα για ενημερώσεις αναπτύξεων, ειδοποιήσεις παρακολούθησης, ειδοποιήσεις εισιτηρίων, υποβολές φορμών και άλλα συμβάντα που πρέπει να εμφανίζονται στη συνομιλία της ομάδας.

Μόνο οι διαχειριστές του χώρου εργασίας μπορούν να δημιουργούν και να διαχειρίζονται εισερχόμενα webhooks.

Δημιουργία webhook

1. Ανοίξτε τις Ρυθμίσεις από την κάτω αριστερή πλευρά της πλαϊνής γραμμής.
2. Επιλέξτε Webhooks.
3. Επιλέξτε Δημιουργία Webhook.
4. Εισαγάγετε ένα σαφές όνομα webhook, όπως CI Deployments.
5. Επιλέξτε το κανάλι όπου θα δημοσιεύονται τα μηνύματα.
6. Προαιρετικά εισαγάγετε URL εικονιδίου.
7. Επιλέξτε Δημιουργία Webhook.

Αντιγραφή του URL webhook

Μετά τη δημιουργία, το HansaChat εμφανίζει το URL του webhook μία φορά. Αντιγράψτε το και αποθηκεύστε το με ασφάλεια στο εξωτερικό εργαλείο που θα στέλνει συμβάντα.

Αν κλείσετε αυτή την οθόνη χωρίς να αποθηκεύσετε το URL, κάντε περιστροφή του URL για να δημιουργηθεί νέο μυστικό. Το προηγούμενο URL παύει να λειτουργεί αμέσως μετά την περιστροφή.

Διαχείριση webhooks

Από τη σελίδα Webhooks, οι διαχειριστές μπορούν:

• Επεξεργασία του ονόματος webhook, του καναλιού, του URL εικονιδίου ή της ενεργής κατάστασης.
• Απενεργοποίηση ενός webhook, ώστε να απορρίπτονται τα νέα μηνύματα χωρίς να διαγράφεται ο webhook.
• Περιστροφή URL για να ακυρωθεί το παλιό μυστικό και να δημιουργηθεί νέο URL.
• Διαγραφή ενός webhook. Τα υπάρχοντα μηνύματα στη συνομιλία δεν αφαιρούνται.

Τεχνική αναφορά

Στείλτε ένα αίτημα POST στο URL του webhook:

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

Το URL ταυτοποιεί τον webhook. Κάθε παράδοση πρέπει επιπλέον να υπογράφεται με το μυστικό του webhook: στείλτε μια κεφαλίδα X-Webhook-Signature με μια χρονική σήμανση και μια υπογραφή HMAC-SHA256 υπολογισμένη πάνω στο σώμα του αιτήματος. Ανυπόγραφες ή ληγμένες παραδόσεις απορρίπτονται με 401. Κρατήστε το πλήρες URL μυστικό.

Υπογράψτε τις παραδόσεις σας

Κάθε αίτημα χρειάζεται μια κεφαλίδα X-Webhook-Signature σε αυτή τη μορφή:

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

Η υπογραφή είναι ένας digest HMAC-SHA256 πάνω στο <χρονική σήμανση>.<σώμα> — η χρονική σήμανση Unix, μια τελεία και το ακατέργαστο σώμα του αιτήματος — με κλειδί το μυστικό του webhook από το URL. Παραδόσεις με χρονική σήμανση παλαιότερη των 5 λεπτών απορρίπτονται, επομένως υπογράψτε κάθε παράδοση ακριβώς πριν την αποστολή της.

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

Αφού το HansaChat επιστρέψει ok, το μήνυμα εμφανίζεται στο επιλεγμένο κανάλι.

Payload συμβατό με Slack

Το endpoint δέχεται payloads JSON συμβατά με Slack με text, blocks και 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."
      }
    }
  ]
}

Τουλάχιστον ένα από τα text, blocks ή attachments πρέπει να περιέχει ευανάγνωστο κείμενο.

Υποστηριζόμενα πεδία

Το μέγιστο μέγεθος payload είναι 1 MB.

Όρια ρυθμού

Η υποδοχή εισερχόμενων webhooks έχει όριο ρυθμού ανά URL webhook.

Κάθε webhook μπορεί να δέχεται έως 10 πιστοποιημένα αιτήματα το λεπτό και έως 100 πιστοποιημένα αιτήματα την ώρα. Όταν επιτευχθεί οποιοδήποτε από τα δύο όρια, το HansaChat επιστρέφει 429 resource_exhausted.

Επικοινωνήστε μαζί μας αν θέλετε να αυξηθεί το όριο ρυθμού.

Τα όρια payload επιβάλλονται ξεχωριστά: το μέγιστο μέγεθος σώματος είναι 1 MB, τα blocks δέχονται έως 50 στοιχεία, τα attachments δέχονται έως 100 στοιχεία και το payload πρέπει να περιέχει ευανάγνωστο κείμενο.

Ταυτοδυναμία

Προσθέστε κεφαλίδα Idempotency-Key όταν το σύστημά σας μπορεί να επαναλάβει το ίδιο συμβάν:

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

Αν το HansaChat λάβει ξανά το ίδιο κλειδί ταυτοδυναμίας για τον ίδιο webhook, επιστρέφει 200 ok χωρίς να δημιουργήσει διπλότυπο μήνυμα.

Απαντήσεις

Τα επιτυχή αιτήματα επιστρέφουν:

ok

Συνηθισμένα σφάλματα:

Συμβουλές ασφαλείας

• Θεωρήστε τα URL webhooks όπως τους κωδικούς πρόσβασης.
• Αποθηκεύστε τα URLs στον διαχειριστή μυστικών του εξωτερικού σας εργαλείου.
• Υπογράψτε κάθε παράδοση με το μυστικό του webhook — τα αυυπόγραφα αιτήματα απορρίπτονται.
• Κάντε περιστροφή του URL αν αποκαλύφθηκε ή χάθηκε.
• Απενεργοποιήστε τα webhooks που δεν χρησιμοποιείτε.
• Χρησιμοποιήστε ένα αποκλειστικό webhook ανά εξωτερικό σύστημα, ώστε η πρόσβαση να μπορεί να ανακληθεί καθαρά.