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

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

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

Άνοιγμα των Webhooks από τις Ρυθμίσεις

Δημιουργία webhook

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

Σελίδα webhooks χωρίς εγγραφές

Φόρμα δημιουργίας webhook

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

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

Το 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. Δεν απαιτείται επιπλέον κεφαλίδα ελέγχου ταυτότητας. Κρατήστε το πλήρες URL μυστικό.

Ελάχιστο αίτημα

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

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

Μήνυμα δοκιμής webhook σε κανάλι

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 πρέπει να περιέχει ευανάγνωστο κείμενο.

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

Πεδίο	Υποχρεωτικό	Σημειώσεις
`text`	Όχι	Περιεχόμενο μηνύματος απλού κειμένου.
`blocks`	Όχι	Μπλοκ τύπου Slack Block Kit. Έως 50 μπλοκ. Υποστηριζόμενοι τύποι μπλοκ: `section`, `header`, `context`, `image`.
`attachments`	Όχι	Συνημμένα τύπου Slack. Έως 100 συνημμένα.

Το μέγιστο μέγεθος 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

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

Κατάσταση	Σώμα	Σημασία
400	`invalid_payload`	Το σώμα JSON δεν μπόρεσε να αναλυθεί.
400	`invalid_blocks`	Το αίτημα περιέχει περισσότερα από 50 μπλοκ.
400	`too_many_attachments`	Το αίτημα περιέχει περισσότερα από 100 συνημμένα.
400	`no_text`	Το payload δεν έχει ευανάγνωστο κείμενο.
429	`resource_exhausted`	Ο webhook ξεπέρασε τα 10 αιτήματα το λεπτό ή τα 100 αιτήματα την ώρα.
404	`no_active_hooks`	Ο χώρος εργασίας, ο webhook, το μυστικό ή η ενεργή κατάσταση δεν είναι έγκυρα.
410	`channel_is_archived`	Το κανάλι-στόχος είναι αρχειοθετημένο.
503	`temporarily_unavailable`	Το HansaChat δεν μπορεί να επεξεργαστεί το μήνυμα αυτή τη στιγμή. Επαναλάβετε αργότερα με το ίδιο `Idempotency-Key`.

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

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