Webhook

Webhook masuk membolehkan sistem lain menghantar mesej ke saluran dengan menghantar JSON ke URL rahsia. Webhook keluar melakukan sebaliknya: ia menghantar mesej ke URL anda, iaitu mesej yang bermula dengan pemicu atau yang dipilih pengguna dalam menu mesej, dan memaparkan apa yang anda jawab.

Di mana untuk mengurus webhook

Buka avatar anda di bahagian kanan atas, kemudian Integrasi. Halaman integrasi komuniti semasa senaraikan Webhook Masuk dan Webhook Keluar. Setiap webhook dimiliki oleh satu komuniti.

Secara lalai, pentadbir komuniti dan pentadbir sistem boleh mencipta webhook. Pentadbir sistem boleh memberikan hak ini kepada peranan lain dalam tetapan kebenaran Konsol Sistem. Pentadbir sistem juga boleh mematikan setiap jenis webhook dalam Konsol Sistem › Integrasi › Pengurusan Integrasi: Aktifkan Webhook Masuk dan Aktifkan Webhook Keluar kedua-duanya aktif secara lalai.

Cipta webhook masuk

1. Dalam Integrasi, pilih Webhook Masuk, kemudian Tambah Webhook Masuk.
2. Isi Tajuk dan Penerangan: ia hanya dipaparkan pada halaman integrasi.
3. Pilih Saluran yang menjadi destinasi lalai untuk mesej. Untuk saluran peribadi, anda mesti menjadi ahlinya.
4. Tanda Kunci ke saluran ini jika penghantar tidak boleh menghantar ke tempat lain.
5. Pilih untuk menetapkan Nama Pengguna dan URL Imej Profil untuk mesejnya (lihat Nama dan ikon).
6. Pilih Simpan. Salin URL yang dipaparkan: https://chat.example.com/hooks/<key>.

Dengan API: POST /api/v4/hooks/incoming dengan {"channel_id", "display_name", "description", "username", "icon_url", "channel_locked"}; id dalam respons ialah kunci. Dari baris arahan: amctl webhook create-incoming --channel <channel id> --user <user> --display-name "CI".

Hantar mesej ke webhook masuk

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

Pelayan menjawab 200 dengan badan ok. Ia juga menerima application/x-www-form-urlencoded dengan JSON dalam medan payload, seperti webhook Slack, jadi alat yang dibuat untuk Slack biasanya berfungsi tanpa perubahan.

Setiap mesej yang dihantar oleh webhook mempunyai tag BOT di sebelah namanya, walaupun ia dipaparkan di bawah nama pencipta, supaya orang lain dapat membezakannya daripada mesej manusia sebenar. Mesej webhook tidak pernah mencetuskan webhook keluar.

Nama dan ikon

Webhook menghantar sebagai individu yang menciptakannya, melainkan pelayan membenarkan penggantian. Dua tetapan dalam Konsol Sistem › Integrasi › Pengurusan Integrasi, kedua-duanya dimatikan secara lalai, mengubah ini:

• Aktifkan integrasi untuk menimpa nama pengguna (ServiceSettings.EnablePostUsernameOverride): Nama Pengguna webhook atau username dalam permintaan dipaparkan sebagai ganti; jika tiada, nama ialah webhook.
• Benarkan integrasi untuk menimpa ikon gambar profil (ServiceSettings.EnablePostIconOverride): Imej Profil webhook, atau icon_url atau icon_emoji permintaan, akan dipaparkan.

Nilai dalam permintaan menang berbanding yang disimpan pada webhook.

Lampiran

Lampiran menambah kandungan berstruktur di bawah teks. Ia mengikuti format lampiran mesej 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
  }]
}

Kad: peringkat dan carta

Antimatter menambah dua medan kepada lampiran, yang dilukis oleh antara muka lalai:

• stages: langkah-langkah paip sebagai pil, sehingga 20. Setiap satu ialah {"name", "status"}, dengan status passed, failed, running, pending, skipped atau canceled.
• chart: carta garisan kecil bagi nilai terkini, {"values": [2 to 200 numbers], "threshold": number, "label": "…"}. Ambang dilukis sebagai garisan putus-putus, untuk had amaran.

{
  "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"}
  }]
}

Antara muka klasik dan klien lain mengabaikan dua medan ini, jadi letakkan juga perkara penting dalam text atau fields.

Cipta webhook keluar

Webhook keluar memantau Awam saluran komuniti. Ia menghantar mesej ke URL anda sama ada apabila perkataan pertama mesej sepadan dengan salah satu perkataan pencetusnya, atau apabila seseorang memilihnya dalam menu mesej (sebuah tindakan mesej).

1. Dalam Integrasi, pilih Webhook Keluar, kemudian Tambah Webhook Keluar.
2. Isi Tajuk dan Penerangan.
3. Pilih Jenis Kandungan permintaan: application/x-www-form-urlencoded atau application/json.
4. Pilih Saluran, masukkan Kata Pemicu (Satu Setiap Baris), atau kedua-duanya. Dengan saluran dan tiada perkataan pencetus, setiap mesej dalam saluran itu dihantar. Dengan kedua-duanya, mesej mesti sepadan dengan kedua-duanya.
5. Di bawah Pemicu Apabila, pilih Perkataan pertama sepadan tepat dengan perkataan pencetus, Perkataan pertama bermula dengan perkataan pencetus, atau Dari menu mesej. Dengan Dari menu mesej, perkataan pencetus hilang, Saluran adalah pilihan (tanpanya, tindakan ditawarkan dalam setiap saluran awam komuniti), dan Tajuk adalah wajib: ia ialah nama tindakan dalam menu.
6. Masukkan URL Panggil Balik (Satu Setiap Baris). Setiap URL menerima setiap mesej yang sepadan.
7. Secara pilihan, tetapkan Nama Pengguna dan Imej Profil yang digunakan untuk balasan. Untuk tindakan dari menu mesej, medan Ikon menggantikan Imej Profil: URL imej .png atau .jpg atau, dalam antara muka lalai Antimatter, imej yang dimuat naik. Menu memaparkannya dalam kelabu; tanpanya, tindakan mendapat ikon neutral.
8. Pilih Simpan dan salin token yang dipaparkan. Perkhidmatan anda menggunakannya untuk memeriksa bahawa permintaan datang dari pelayan anda.

Melalui API: POST /api/v4/hooks/outgoing dengan {"team_id", "channel_id", "trigger_words", "trigger_when", "callback_urls", "content_type", "display_name"} (trigger_when: 0 untuk padanan tepat, 1 untuk "mula dengan", 2 untuk "dari menu mesej"). Webhook dengan trigger_when 2 tidak memerlukan perkataan pemicu dan memerlukan display_name. Muat naik ikonnya dengan POST /api/v4/hooks/outgoing/{hook_id}/icon (multipart, medan image: PNG, JPEG atau GIF, disimpan sebagai PNG 128 px); icon_urlnya kemudian menunjuk ke GET /api/v4/hooks/outgoing/{hook_id}/icon.

Permintaan keluar

Antimatter menghantar POST dengan medan-medan ini, sebagai JSON atau form-encoded bergantung pada jenis kandungan:

{
  "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": ""
}

Bandingkan token dengan token webhook sebelum melakukan apa-apa. Dalam versi yang dikodkan sebagai borang, timestamp adalah dalam saat, bukan milisaat. Pelayan akan menunggu jawapan anda selama yang dibenarkan oleh Masa tamat permintaan integrasi (30 saat secara lalai, ServiceSettings.OutgoingIntegrationRequestsTimeout).

Balas kepada webhook keluar

Untuk memuat naik balasan, jawab dengan JSON. Untuk tidak memuat naik apa-apa, jawab dengan badan kosong.

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

• text dan attachments: balasan. Tanpa mana-mana daripada ini, tiada apa yang akan diposkan.
• response_type: comment memposkan balasan dalam bebenang mesej pencetus; sebaliknya, ia akan dihantar ke saluran.
• username, icon_url: dipaparkan apabila pelayan membenarkan penggantian; nilai milik webhook itu sendiri akan digunakan sebaliknya.
• props, type, priority: seperti untuk webhook masuk.

Balasan diposkan sebagai pencipta webhook, di bawah nama yang digantikan jika ada. Untuk apa-apa yang lebih panjang daripada jawapan ringkas, jawab serta-merta dan pos kemudian menggunakan webhook masuk atau API.

Aksi mesej

Aksi mesej ialah webhook keluar dengan Pemicu Apabila ditetapkan kepada Dari menu mesej. Ia tidak akan dipicu pada mesej yang diposkan. Sebaliknya, orang akan melihatnya dalam menu mesej: Aksi mesej (⋯) › Lagi Tindakan, di bawah tajuk Integrasi, dengan ikonnya. Antaramuka klasik tidak memaparkan aksi mesej. Memilihnya akan menghantar mesej tersebut ke URL pautan balik, dan pemberitahuan ringkas akan menyatakan Dihantar ke nama tindakan tersebut, atau memaparkan ephemeral_text anda.

• Di mana ia dipaparkan: dalam saluran webhook tersebut, atau, tanpa saluran, dalam setiap Saluran Awam komunitinya. Hanya Saluran Awam yang mempunyai aksi mesej.
• Tetamu hanya akan mendapat tindakan yang diikat kepada saluran yang mereka sertai, bukan tindakan yang merangkumi seluruh komuniti.
• Saluran yang diarkibkan dan sahaja-baca: mesej masih boleh dihantar. Mengarkibkan saluran akan memadam webhook yang diikat kepadanya, jadi saluran yang diarkibkan hanya akan mengekalkan tindakan yang merangkumi seluruh komuniti. Jawapan yang tidak boleh diposkan oleh pengguna tersebut akan dipaparkan kepada mereka sahaja.
• Had kadar: setiap orang boleh menjalankan 10 aksi mesej dalam satu minit, selepas pecutan 5. Jika melebihi had ini, pelayan akan menjawab 429.
• Rangkaian peribadi: seperti webhook keluaran lain, alamat dalaman mesti dibenarkan dalam Benarkan sambungan dalaman tidak dipercayai kepada.

Permintaan

Beban (payload) dihantar sebagai JSON atau kod bentuk (form-encoded), seperti yang dinyatakan oleh jenis kandungan 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 dan user_name ialah individu yang memilih tindakan; post_user_id dan post_user_name ialah pengarang mesej tersebut.
• Hanya mesej itu yang dihantar, bukan sebahagian daripada benangnya.
• files menyenaraikan fail mesej hanya jika individu yang memilih tindakan boleh memuat turunnya. Memuat turun link memerlukan sesi atau token, seperti mana-mana fail dalam API.
• Mesej yang dibakar selepas dibaca (burn-on-read) dihantar tanpa teks dan failnya, dengan burn_on_read ditetapkan kepada true.
• Jika dikod bentuk (form-encoded), fail datang sebagai medan file_id, file_name dan file_link yang diulang, dalam urutan yang sama.

Jawapan

Jawab seperti mana-mana webhook keluaran (lihat Balas kepada webhook keluaran): text atau attachments memuat naik balasan dalam saluran, dan "response_type": "comment" memuat naik balasan dalam benang mesej tersebut. Anda juga boleh menjawab dengan ephemeral_text (dipotong kepada 300 aksara): ia dipaparkan hanya kepada individu yang memilih tindakan, dalam notis. Badan kosong tidak memuat naik apa-apa.

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

Dengan API

• GET /api/v4/channels/{channel_id}/message_actions: tindakan yang boleh anda pilih dalam saluran, dengan id, display_name, description dan icon_url. Token atau URL panggil balik (callback) tidak dikembalikan.
• POST /api/v4/posts/{post_id}/message_actions/{hook_id}: menjalankan tindakan pada mesej yang boleh anda baca. Ia menjawab {"ephemeral_text"}.

Apabila webhook tidak berfungsi

• 501 dari URL hook: webhook masuk dimatikan pada pelayan.
• 400 "Failed to decode the payload…": JSON tidak sah, atau medan borang tidak dinamakan payload. "No text specified." bermaksud permintaan tidak mempunyai text atau attachments.
• 403: webhook dikunci kepada saluran lain, atau pemiliknya tidak lagi boleh membaca saluran tersebut.
• Webhook keluaran tidak pernah dicetuskan: saluran adalah peribadi, pencetus bukan perkataan pertama, mesej datang dari webhook, atau webhook ditetapkan untuk dicetuskan Daripada menu mesej.
• Tindakan mesej tidak ada dalam menu: saluran adalah peribadi, tindakan terikat kepada saluran lain, individu tersebut adalah tetamu dan tindakan tiada saluran, atau webhook keluaran dimatikan.
• 404 semasa menjalankan tindakan mesej: tindakan tidak wujud, atau ia tidak merangkumi saluran mesej tersebut untuk individu tersebut. 429: individu tersebut menjalankan lebih daripada 10 tindakan dalam satu minit. 502: tiada satu pun URL panggil balik (callback) dapat dicapai (log mempunyai sebabnya).
• Log: dengan Aktifkan Penyahpepijatan Webhook dihidupkan (LogSettings.EnableWebhookDebugging), dan tahap log pada DEBUG, pelayan merekodkan muatan (payload) permintaan masuk yang gagal. Panggilan keluar yang gagal direkodkan sebagai Outgoing Webhook POST failed.