Webhooks

Ένα εισερχόμενο webhook επιτρέπει σε ένα άλλο σύστημα να δημοσιεύει σε ένα κανάλι αποστέλλοντας JSON σε μια μυστική διεύθυνση URL. Ένα εξερχόμενο webhook κάνει το αντίστροφο: στέλνει μηνύματα στη διεύθυνση URL σας, αυτά που ξεκινούν με μια λέξη ενεργοποίησης ή αυτά που κάποιος τα επιλέγει από το μενού μηνύματος, και δημοσιεύει ό,τι απαντήσετε.

Πού διαχειρίζεστε τα webhooks

Ανοίξτε το μενού της ομάδας, στη συνέχεια Ρυθμίσεις ομάδας και κάντε κλικ στην επιλογή Ολοκληρώσεις στο τέλος των καρτελών της. Οι σελίδες ολοκληρώσεων της τρέχουσας ομάδας εμφανίζουν τη λίστα Εισερχόμενα Webhooks και Εξερχόμενα Webhooks. Κάθε webhook ανήκει σε μία μόνο ομάδα.

By default, community admins and system admins can create webhooks. A system admin can give the right to other roles in the permission settings of the System Console. A system admin can also turn each kind off in System Console › Integrations › Integration Management: Enable Incoming Webhooks and Enable Outgoing Webhooks are both on by default.

Δημιουργία εισερχόμενου webhook

1. Στην ενότητα Ολοκληρώσεις, επιλέξτε Εισερχόμενα Webhooks και στη συνέχεια Προσθήκη εισερχόμενου Webhook.
2. Συμπληρώστε έναν Τίτλο και μια Περιγραφή: εμφανίζονται μόνο στις σελίδες ολοκληρώσεων.
3. Επιλέξτε το Κανάλι στο οποίο θα αποστέλλονται τα μηνύματα κατ' εξόρθωση. Για ένα ιδιωτικό κανάλι, πρέπει να είστε μέλος του.
4. Επιλέξτε Κλείδωμα σε αυτό το κανάλι αν οι αποστολείς δεν πρέπει να μπορούν να δημοσιεύουν σε άλλα κανάλια.
5. Επιλέξτε προαιρετικά ένα Όνομα χρήστη και ένα URL Εικόνας προφίλ για τα μηνύματά του (βλ. Όνομα και εικονίδιο).
6. Επιλέξτε Αποθήκευση. Αντιγράψτε το URL που εμφανίζεται: https://chat.example.com/hooks/<key>.

Με το API: POST /api/v4/hooks/incoming με {"channel_id", "display_name", "description", "username", "icon_url", "channel_locked"}· το id της απάντησης είναι το κλειδί. Από τη γραμμή εντολών: amctl webhook create-incoming --channel <channel id> --user <user> --display-name "CI".

Αποστολή μηνύματος σε εισερχόμενο webhook

curl -X POST https://chat.example.com/hooks/xgh5ycrx1jf7mbs9w8z4c8e7ho \
  -H 'Content-Type: application/json' \
  -d '{"text": "Deploy of **api 2.4.0** finished :white_check_mark:"}'

Ο διακομιστής απαντά με 200 και σώμα ok. Δέχεται επίσης application/x-www-form-urlencoded με το JSON σε πεδίο payload, όπως κάνουν τα webhooks του Slack, οπότε τα εργαλεία που έχουν δημιουργηθεί για το Slack συνήθως λειτουργούν χωρίς αλλαγές.

Κάθε μήνυμα που δημοσιεύει ένα webhook φέρει δίπλα στο όνομά του την ετικέτα BOT, ακόμη και όταν εμφανίζεται κάτω από το όνομα του δημιουργού του, ώστε να μπορεί κανείς να το διακρίνει από ένα μήνυμα πραγματικού χρήστη. Τα μηνύματα webhook δεν ενεργοποιούν ποτέ исходящие webhooks.

Όνομα και εικόνα

Ένα webhook δημοσιεύει ως ο χρήστης που το δημιούργησε, εκτός αν ο διακομιστής επιτρέπει υπερβάσεις. Δύο ρυθμίσεις στις Κονσόλα συστήματος › Ολοκληρώσεις › Διαχείριση ολοκληρώσεων, και οι δύο απενεργοποιημένες εξ ορισμού, αλλάζουν αυτό:

• Ενεργοποίηση ολοκληρώσεων για την υπέρβαση των ονομάτων χρηστών (ServiceSettings.EnablePostUsernameOverride): εμφανίζεται το Όνομα χρήστη του webhook ή το username του αιτήματος. Αν δεν υπάρχει κανένα από τα δύο, το όνομα είναι webhook.
• Ενεργοποίηση ολοκληρώσεων για υπέρβαση εικονιδίων εικόνας προφίλ (ServiceSettings.EnablePostIconOverride): εμφανίζεται η Εικόνα προφίλ του webhook, ή το icon_url ή το icon_emoji του αιτήματος.

Μια τιμή στο αίτημα υπερισχύει της τιμής που αποθηκεύεται στο webhook.

Συνημμένα

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

{
  "text": "Build failed on `main`",
  "attachments": [{
    "fallback": "main #1902 failed",
    "color": "#d24b4e",
    "author_name": "GitHub Actions",
    "author_icon": "https://chat.example.com/static/ci.png",
    "title": "main #1902 failed",
    "title_link": "https://ci.example.com/runs/1902",
    "text": "Commit `0f4d8e2` by Jonas Weber",
    "fields": [
      {"title": "Branch", "value": "zephyr-3.7", "short": true},
      {"title": "Duration", "value": "3m 40s", "short": true}
    ],
    "footer": "Lumen CI",
    "ts": 1760000000
  }]
}

Κάρτες: στάδια και διαγράμματα

Το Antimatter προσθέτει δύο πεδία στα συνημμένα, τα οποία απεικονίζει η προεπιλεγμένη διεπαφή:

• stages: τα βήματα μιας διαδικασίας ως «κουκκίδες», έως 20. Κάθε ένα είναι {"name", "status"}, με κατάσταση passed, failed, running, pending, skipped ή canceled.
• chart: ένα μικρό γραμμικό διάγραμμα πρόσφατων τιμών, {"values": [2 to 200 numbers], "threshold": number, "label": "…"}. Η κατώτατη τιμή (threshold) σχεδιάζεται ως διακεκομμένη γραμμή, για το όριο μιας ειδοποίησης.

{
  "attachments": [{
    "color": "danger",
    "title": "main #1902 failed",
    "stages": [
      {"name": "build", "status": "failed"},
      {"name": "unit", "status": "skipped"},
      {"name": "publish", "status": "skipped"}
    ]
  }, {
    "color": "warning",
    "title": "API latency above 400 ms",
    "chart": {"values": [210, 230, 260, 390, 450, 470], "threshold": 400, "label": "p95 latency, ms"}
  }]
}

Η κλασική διεπαφή και άλλοι πελάτες αγνοούν αυτά τα δύο πεδία, οπότε τοποθετήστε τα βασικά στοιχεία και στο text ή fields.

Δημιουργία исходящего webhook

Ένα исходящее webhook παρακολουθεί τα Δημόσια κανάλια μιας κοινότητας. Στέλνει ένα μήνυμα στη διεύθυνση URL σας είτε όταν η πρώτη λέξη του μηνύματος ταιριάζει με μία από τις λέξεις ενεργοποίησης του, είτε όταν κάποιος το επιλέγει από το μενού του μηνύματος (μία ενέργεια μηνύματος).

1. Στην ενότητα Ολοκληρώσεις, επιλέξτε Εξερχόμενα Webhooks και στη συνέχεια Προσθήκη εξερχόμενου Webhook.
2. Συμπληρώστε τον Τίτλο και την Περιγραφή.
3. Επιλέξτε τον Τύπο περιεχομένου του αιτήματος: application/x-www-form-urlencoded ή application/json.
4. Επιλέξτε ένα Κανάλι, εισάγετε Λέξεις ενεργοποίησης (μία ανά γραμμή) ή και τα δύο. Αν ορίσετε κανάλι χωρίς λέξεις ενεργοποίησης, στέλνεται κάθε μήνυμα του καναλιού. Αν ορίσετε και τα δύο, το μήνυμα πρέπει να ταιριάζει και στα δύο.
5. Στο πεδίο Ενεργοποίηση όταν, επιλέξτε Το πρώτο όνομα ταιριάζει ακριβώς με μια λέξη ενεργοποίησης, Το πρώτο όνομα ξεκινά με μια λέξη ενεργοποίησης ή Από το μενού μηνύματος. Αν επιλέξετε Από το μενού μηνύματος, οι λέξεις ενεργοποίησης εξαφανίζονται, το πεδίο Κανάλι είναι προαιρετικό (αν παραληφθεί, η ενέργεια προσφέρεται σε κάθε δημόσιο κανάλι της κοινότητας) και το πεδίο Τίτλος είναι υποχρεωτικό: αποτελεί το όνομα της ενέργειας στο μενού.
6. Εισάγετε τις URL επανακατεύθυνσης (ένα ανά γραμμή). Κάθε URL λαμβάνει κάθε μήνυμα που ταιριάζει.
7. Μπορείτε προαιρετικά να ορίσετε το Όνομα χρήστη και την Εικόνα προφίλ που θα χρησιμοποιηθούν για τις απαντήσεις. Για μια ενέργεια από το μενού μηνύματος, το πεδίο Εικονίδιο αντικαθιστά την Εικόνα προφίλ: η διεύθυνση URL μιας εικόνας .png ή .jpg ή, στη προεπιλεγμένη διεπαφή του Antimatter, μια ανεβασμένη εικόνα. Το μενού την εμφανίζει σε γκρι. Αν δεν υπάρχει, η ενέργεια λαμβάνει ένα ουδέτερο εικονίδιο.
8. Επιλέξτε Αποθήκευση και αντιγράψτε το token που εμφανίζεται. Η υπηρεσία σας το χρησιμοποιεί για να ελέγχει ότι τα αιτήματα προέρχονται από τον διακομιστή σας.

Μέσω της API: POST /api/v4/hooks/outgoing με {"team_id", "channel_id", "trigger_words", "trigger_when", "callback_urls", "content_type", "display_name"} (trigger_when: 0 για ακριβή ταιριάζει, 1 για «ξεκινά με», 2 για «από το μενού μηνύματος»). Ένα webhook με trigger_when 2 δεν απαιτεί λέξεις ενεργοποίησης και χρειάζεται display_name. Ανέβαστε το εικονίδιό του με POST /api/v4/hooks/outgoing/{hook_id}/icon (multipart, πεδίο image: PNG, JPEG ή GIF, αποθηκεύεται ως PNG 128 px); το icon_url του δείχνει τότε στο GET /api/v4/hooks/outgoing/{hook_id}/icon.

Το исходящее αίτημα

Το Antimatter στέλνει ένα POST με αυτά τα πεδία, ως JSON ή form-encoded ανάλογα με το content type:

{
  "token": "6kd1ofo5ojr5zgu5ipfipybgnc",
  "team_id": "…",
  "team_domain": "lumen-labs",
  "channel_id": "…",
  "channel_name": "ops-alerts",
  "timestamp": 1760010000000,
  "user_id": "…",
  "user_name": "priya",
  "post_id": "…",
  "text": "deploy api 2.4.0",
  "trigger_word": "deploy",
  "file_ids": ""
}

Συγκρίνετε το token με το token του webhook πριν κάνετε οτιδήποτε. Στην κωδικοποιημένη μορφή φόρμας, το timestamp είναι σε δευτερόλεπτα και όχι σε χιλιοστά του δευτερολέπτου. Ο διακομιστής περιμένει την απάντησή σας για όσο επιτρέπει το Χρονόριο αιτήσεων ολοκληρώσεων (30 δευτερόλεπτα από προεπιλογή, ServiceSettings.OutgoingIntegrationRequestsTimeout).

Απάντηση σε ένα исходящее webhook

Για να δημοσιεύσετε μια απάντηση, απαντήστε με JSON. Για να μην δημοσιεύσετε τίποτα, απαντήστε με κενό σώμα.

{
  "text": "Deploying **api 2.4.0** to staging…",
  "response_type": "comment",
  "username": "deploy-bot",
  "icon_url": "https://chat.example.com/static/deploy.png"
}

• text και attachments: η απάντηση. Χωρίς κανένα από τα δύο, δεν δημοσιεύεται τίποτα.
• response_type: το comment δημοσιεύει την απάντηση στο νήμα του μηνύματος που πυροδότησε το webhook. Αλλιώς, πηγαίνει στο κανάλι.
• username, icon_url: εμφανίζονται όταν ο διακομιστής επιτρέπει αντικαταστάσεις. Αλλιώς, χρησιμοποιούνται οι ίδιες τιμές του webhook.
• props, type, priority: όπως για τα εισερχόμενα webhooks.

Η απάντηση δημοσιεύεται ως ο δημιουργός του webhook, με το αντικαταστασμένο όνομα αν υπάρχει. Για οτιδήποτε μεγαλύτερο από μια σύντομη απάντηση, απαντήστε αμέσως και δημοσιεύστε αργότερα με ένα εισερχόμενο webhook ή το API.

Ενέργειες μηνύματος

Μια ενέργεια μηνύματος είναι ένα исходящее webhook με Ενεργοποίηση όταν ρυθμισμένο σε Από το μενού μηνύματος. Δεν ενεργοποιείται ποτέ σε δημοσιευμένα μηνύματα. Αντίθετα, οι χρήστες τη βλέπουν στο μενού ενός μηνύματος: Ενέργειες μηνύματος (⋯) › Περισσότερες ενέργειες, κάτω από την κεφαλίδα Ολοκληρώσεις, με το εικονίδιό της. Η κλασική διεπαφή δεν εμφανίζει ενέργειες μηνύματος. Η επιλογή της στέλνει μόνο αυτό το μήνυμα στις διευθύνσεις κλήσης και μια σύντομη ειδοποίηση αναφέρει Απεστάλη σε το όνομα της ενέργειας ή εμφανίζει το ephemeral_text σας.

• Πού εμφανίζεται: στο κανάλι του webhook ή, χωρίς κανάλι, σε κάθε δημόσιο κανάλι της κοινότητας. Μόνο τα δημόσια κανάλια έχουν ενέργειες μηνύματος.
• Οι Επισκέπτες λαμβάνουν μόνο τις ενέργειες που είναι συνδεδεμένες με ένα κανάλι στο οποίο βρίσκονται, όχι τις κοινές σε ολόκληρη την κοινότητα.
• Αρχειοθετημένα και κανάλια μόνο για ανάγνωση: το μήνυμα μπορεί ακόμα να σταλεί. Η αρχειοθέτηση ενός καναλιού διαγράφει τα webhooks που είναι συνδεδεμένα με αυτό, οπότε ένα αρχειοθετημένο κανάλι διατηρεί μόνο τις κοινές σε ολόκληρη την κοινότητα ενέργειες. Μια απάντηση που ο χρήστης δεν μπορούσε να δημοσιεύσει εκεί εμφανίζεται μόνο σε αυτόν.
• Όριο ρυθμού: κάθε χρήστης μπορεί να εκτελέσει 10 ενέργειες μηνύματος ανά λεπτό, μετά από μια έκρηξη 5. Πάνω από αυτό, ο διακομιστής απαντά με 429.
• Ιδιωτικά δίκτυα: όπως και για άλλα исходящие webhooks, οι εσωτερικές διευθύνσεις πρέπει να επιτρέπονται στο Επιτρέπει μη αξιόπιστες εσωτερικές συνδέσεις προς.

Το αίτημα

Το φορτίο στέλνεται ως JSON ή form-encoded, όπως ορίζει ο τύπος περιεχομένου του webhook:

{
  "token": "6kd1ofo5ojr5zgu5ipfipybgnc",
  "trigger": "message_action",
  "team_id": "…",
  "team_domain": "lumen-labs",
  "channel_id": "…",
  "channel_name": "ops-alerts",
  "timestamp": 1760010000000,
  "user_id": "…",
  "user_name": "priya",
  "post_id": "…",
  "post_root_id": "",
  "post_create_at": 1760009000000,
  "post_user_id": "…",
  "post_user_name": "jonas",
  "permalink": "https://chat.example.com/lumen-labs/pl/…",
  "text": "The staging database is full again",
  "files": [{"id": "…", "name": "df.txt", "link": "https://chat.example.com/api/v4/files/…"}],
  "priority": "",
  "requested_ack": false,
  "burn_on_read": false
}

• Τα user_id και user_name είναι ο χρήστης που επέλεξε την ενέργεια· τα post_user_id και post_user_name ο δημιουργός του μηνύματος.
• Στέλνεται μόνο αυτό το μήνυμα, ποτέ το υπόλοιπο του νήματος.
• Τα files απαριθμούν τα αρχεία του μηνύματος μόνο όταν ο χρήστης που επέλεξε την ενέργεια μπορεί να τα κατεβάσει. Η λήψη ενός link απαιτεί μια συνεδρία ή ένα token, όπως και οποιοδήποτε αρχείο της API.
• Ένα μήνυμα που καίγεται κατά την ανάγνωση αποστέλλεται χωρίς το κείμενο και τα αρχεία του, με το burn_on_read ορισμένο σε true.
• Σε κωδικοποίηση φόρμας, τα αρχεία έρχονται ως επαναλαμβανόμενα πεδία file_id, file_name και file_link, στην ίδια σειρά.

Η απάντηση

Απαντάτε όπως σε κάθε εξερχόμενο webhook (βλ. Απάντηση σε εξερχόμενο webhook): το text ή τα attachments δημοσιεύουν μια απάντηση στο κανάλι, ενώ το "response_type": "comment" τη δημοσιεύει στο νήμα του μηνύματος. Μπορείτε επίσης να απαντήσετε με ephemeral_text (κομμένο στα 300 χαρακτήρες): εμφανίζεται μόνο στον χρήστη που επέλεξε την ενέργεια, στην ειδοποίηση. Ένα κενό σώμα δεν δημοσιεύει τίποτα.

{"ephemeral_text": "Ticket OPS-412 created"}

Με το API

• GET /api/v4/channels/{channel_id}/message_actions: οι ενέργειες που μπορείτε να επιλέξετε σε ένα κανάλι, με id, display_name, description και icon_url. Δεν επιστρέφονται ούτε token ούτε URL επεξεργασίας.
• POST /api/v4/posts/{post_id}/message_actions/{hook_id}: εκτελεί μια ενέργεια σε ένα μήνυμα που μπορείτε να διαβάσετε. Απαντά με {"ephemeral_text"}.

Όταν ένα webhook δεν λειτουργεί

• 501 από το URL του hook: τα εισερχόμενα webhooks είναι απενεργοποιημένα στον διακομιστή.
• 400 "Failed to decode the payload…": το JSON είναι άκυρο ή το πεδίο της φόρμας δεν ονομάζεται payload. Το "No text specified." σημαίνει ότι το αίτημα δεν έχει ούτε text ούτε attachments.
• 403: το webhook είναι κλειδωμένο σε άλλο κανάλι ή ο ιδιοκτήτης του δεν μπορεί πλέον να διαβάσει το κανάλι.
• Ένα εξερχόμενο webhook δεν ενεργοποιείται ποτέ: το κανάλι είναι ιδιωτικό, η λέξη-πρόκληση δεν είναι η πρώτη λέξη, το μήνυμα προέρχεται από webhook, ή το webhook ρυθμίζεται να ενεργοποιείται Από το μενού μηνύματος.
• Μια ενέργεια μηνύματος δεν εμφανίζεται στο μενού: το κανάλι είναι ιδιωτικό, η ενέργεια συνδέεται με άλλο κανάλι, ο χρήστης είναι επισκέπτης και η ενέργεια δεν έχει κανάλι, ή τα εξερχόμενα webhooks είναι απενεργοποιημένα.
• 404 κατά την εκτέλεση μιας ενέργειας μηνύματος: η ενέργεια δεν υπάρχει, ή δεν καλύπτει το κανάλι του μηνύματος για αυτόν τον χρήστη. 429: ο χρήστης εκτέλεσε πάνω από 10 ενέργειες σε ένα λεπτό. 502: κανένα από τα URL επεξεργασίας δεν ήταν προσβάσιμο (ο λόγος αναγράφεται στο αρχείο καταγραφής).
• Η ανάρτηση σε φόρουμ απορρίπτεται: το μήνυμα του webhook χρειάζεται τίτλο (props.am_thread_title). Το σφάλμα αναφέρει τον λόγο, όπως app.post.forum.title_required.app_error, αντί για ένα γενικό σφάλμα αποτυχίας (δείτε Τύποι καναλιών).
• Καταγραφές: με το Ενεργοποίηση αποσφαλμάτωσης Webhook ενεργοποιημένο (LogSettings.EnableWebhookDebugging) και το επίπεδο καταγραφής σε DEBUG, ο διακομιστής καταγράφει τα φορτία (payloads) των αποτυχημένων εισερχόμενων αιτημάτων. Τα αποτυχημένα εξερχόμενα αιτήματα καταγράφονται ως Outgoing Webhook POST failed.