Mga Webhook

Ang incoming webhook ay nagpapahintulot sa ibang system na mag-post sa isang channel sa pamamagitan ng pagpadala ng JSON sa isang secret URL. Ang outgoing webhook ay gumagawa ng kabaligtaran: nagpapadala ito ng mga mensahe sa iyong URL, na nagsisimula sa trigger word o pinili ng tao sa menu ng mensahe, at nagpo-post ng iyong sagot.

Saan pamahalaan ang mga webhook

Buksan ang iyong avatar sa itaas na kanang sulok, tapos pindutin ang Mga Integration. Sa mga pahina ng integration ng kasalukuyang community, nakalista ang mga Mga Incoming Webhook at Mga Outgoing Webhook. Bawat webhook ay kabilang sa isang community.

Sa default, ang mga admin ng community at system admin ang makagawa ng webhook. Maaaring bigyan ng karapatan ang ibang mga role ng isang system admin sa mga setting ng permission ng System Console. Maaari ring patayin ng isang system admin ang bawat uri sa System Console › Mga Integration › Pamamahala ng Integration: ang Paganahin ang Incoming Webhooks at Pahintulutan ang mga Outgoing Webhooks ay naka-on sa default.

A channel with messages from a CI bot and from GitHub, shown as cards with fields, pipeline stages and a button — Mga mensahe ng integrations na ginuhit bilang card: mga field, mga yugto ng pipeline, at isang action button.

Paggawa ng incoming webhook

Sa Mga Integration, piliin ang Mga Incoming Webhook, tapos pindutin ang Magdagdag ng Incoming Webhook.
Punan ang Pamagat at Paglalarawan: ito ay ipapakita lamang sa mga pahina ng integration.
Piliin ang Channel na default na destinasyon ng mga mensahe. Para sa pribadong channel, dapat ka ay miyembro nito.
Tikman ang I-lock sa channel na ito kung hindi dapat makapag-post ang mga nagpapadala sa ibang lugar.
Pangalawang, itakda ang Username at Larawan sa Profile URL para sa mga mensahe nito (tingnan ang Pangalan at icon).
Piliin ang I-save. Kopiyahin ang URL na ipinakita: https://chat.example.com/hooks/<key>.

Ang URL ang tanging sekreto: kahit sino na may hawak nito ay makapag-post sa channel. Iwasan ang paglalagay nito sa mga pampublikong repository, at burahin ang webhook kung nalaglag.

Gamit ang API: POST /api/v4/hooks/incoming na may {"channel_id", "display_name", "description", "username", "icon_url", "channel_locked"}; ang id ng tugon ang key. Mula sa command line: amctl webhook create-incoming --channel <channel id> --user <user> --display-name "CI".

Pagpadala ng mensahe sa incoming 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:"}'

Sasagutin ng server ang 200 na may body na ok. Tinatanggap din nito ang application/x-www-form-urlencoded na may JSON sa isang payload field, gaya ng ginagawa ng mga webhook ng Slack, kaya karaniwang gumagana ang mga tool na gawa para sa Slack nang walang pagbabago.

Field	Kahulugan
`text`	Ang mensahe, sa Markdown. Kinakailangan maliban kung may `attachments`. Ang mas mahaba sa limitasyon ng mensahe ng server ay hahatiin sa ilang mensahe.
`channel`	Iba pang channel ng community ng webhook, ayon sa pangalan (`ops-alerts` o `#ops-alerts`), o `@username` para sa direct message mula sa may-ari ng webhook. Tinatanggi kapag naka-lock ang webhook sa kanyang channel. Ang lumang pangalan na `town-square` ay tumatawid pa rin sa default channel ng community, na ngayon ay tinatawag na `general`.
`username`, `icon_url`, `icon_emoji`	Ang pangalan at larawan na ipapakita, kapag pinapayagan ng server ang mga override.
`attachments`	Mga attachment ng mensahe, na ipinapakita bilang mga card (sa ibaba).
`props`	Mga karagdagang property na nakatago sa mensahe, para sa mga app na babasahin ito.
`type`	Isang custom na uri ng post, tulad ng `custom_poll`, para sa isang app na ipinapakita ito. Ang mga uri na nagsisimula sa `system_` ay itatanggihan.
`root_id`	Ang ID ng unang mensahe ng isang thread, upang sumagot sa thread na iyon.
`priority`	Ang priyoridad ng mensahe, halimbawa `{"priority": "urgent"}`.
`silent`	Ang `true` ay nagpapadala ng mensahe nang walang push notification.

Bawat mensahe na ipinopost ng webhook ay may BOT tag sa tabi ng pangalan nito, kahit ipinapakita ito sa ilalim ng pangalan ng tagalikha nito, upang maibigay-iba ito mula sa mensahe ng tunay na tao. Hindi nag-trigger ang mga mensahe ng webhook ng mga outgoing webhook.

Pangalan at icon

Ang webhook ay nagpo-post bilang ang tao na gumawa nito, maliban kung pinapayagan ng server ang mga override. Dalawang setting sa System Console › Mga Integration › Pamamahala ng Integration, parehong naka-off sa default, ang nagbabago nito:

Pahintulutan ang mga integration na palitan ang mga username (ServiceSettings.EnablePostUsernameOverride): ipapakita ang Username ng webhook o ang username ng request; kung wala ang alinman, ang pangalan ay webhook.
Pahintulutan ang mga integrations na palitan ang mga profile picture icons (ServiceSettings.EnablePostIconOverride): ipapakita ang Larawan sa Profile ng webhook, o ang icon_url o icon_emoji ng request.

Ang halaga sa request ay mananalo kaysa sa nakatago sa webhook.

Mga Attachment

Ang mga attachment ay nagdaragdag ng structured content sa ilalim ng teksto. Sumusunod sila sa format ng message attachment ng 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
  }]
}

Field	Kahulugan
`fallback`	Plain text para sa mga lugar na hindi maipakita ang card, tulad ng mga notisikasyon.
`color`	Ang kulay na bar: isang hex color, o `good`, `warning`, `danger`.
`pretext`	Teksto sa itaas ng card.
`author_name`, `author_link`, `author_icon`	Isang maliit na header line.
`title`, `title_link`	Ang pamagat ng card, opsyonal na link.
`text`	Ang katawan ng card, sa Markdown.
`fields`	Isang listahan ng `{"title", "value", "short"}`; ang mga `short` field ay naka-parallel.
`image_url`, `thumb_url`	Isang malaking larawan sa ibaba, o isang maliit sa gilid.
`footer`, `footer_icon`, `ts`	Isang footer line at oras (Unix seconds).
`actions`	Mga button at menu: tingnan ang Interactive messages.

Mga Card: mga stage at chart

Idinagdag ng Antimatter ang dalawang field sa mga attachment, na ipinapakita ng default interface:

stages: ang mga hakbang ng isang pipeline bilang pills, hanggang 20. Ang bawat isa ay {"name", "status"}, na may status na passed, failed, running, pending, skipped o canceled.
chart: isang maliit na line chart ng mga kamakailang value, {"values": [2 to 200 numbers], "threshold": number, "label": "…"}. Ang threshold ay ipinapakita bilang dashed line, para sa limit ng isang alert.

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

Iniiwasan ng classic interface at ibang client ang dalawang field na ito, kaya ilagay ang mga pangunahing impormasyon sa text o fields din.

Gumawa ng outgoing webhook

Sinusubaybayan ng outgoing webhook ang mga pampublikong channel ng isang community. Nagpapadala ito ng mensahe sa iyong URL kapag ang unang salita ng mensahe ay tumutugma sa isa sa mga trigger word nito, o kapag pinili ito ng tao sa menu ng mensahe (isang message action).

Sa Mga Integration, piliin ang Mga Outgoing Webhook, tapos pindutin ang Magdagdag ng Outgoing Webhook.
Punan ang Pamagat at Paglalarawan.
Piliin ang Content Type ng request: application/x-www-form-urlencoded o application/json.
Piliin ang Channel, ilagay ang Mga Trigger Word (Isa Bawat Linya), o pareho. Kung may channel at walang trigger words, ang bawat mensahe ng channel na iyon ay ipapadala. Kung may pareho, ang mensahe ay dapat tumugma sa pareho.
Sa ilalim ng Paggamit ng trigger words, piliin ang Ang unang salita ay eksaktong tumutugma sa trigger word, Nagsisimula ang unang salita sa trigger word, o Mula sa menu ng mensahe. Sa Mula sa menu ng mensahe, nawawala ang mga trigger word, opsyonal ang Channel (kung wala, iniaoffer ang action sa bawat pampublikong channel ng community), at kinakailangan ang Pamagat: ito ang pangalan ng action sa menu.
Ilagay ang Mga Callback URL (Isa sa Bawat Linya). Bawat URL ay makakatanggap ng bawat tumutugmang mensahe.
Opsyonal na itakda ang Username at Larawan sa Profile na gagamitin para sa mga sagot. Para sa action mula sa menu ng mensahe, ang field na Icon ay nagpapalit sa Larawan sa Profile: ang URL ng isang .png o .jpg na imahe o, sa default na interface ng Antimatter, isang na-upload na imahe. Ipinapakita ito sa menu sa kulay abo; kung wala, mayroon itong neutral na icon.
Piliin ang I-save at kopiyahin ang token na ipinakita. Ginagamit nito ng iyong service upang suriin na mula sa iyong server ang mga request.

Gamit ang API: POST /api/v4/hooks/outgoing na may {"team_id", "channel_id", "trigger_words", "trigger_when", "callback_urls", "content_type", "display_name"} (trigger_when: 0 para sa eksaktong tugma, 1 para sa "nagsisimula sa", 2 para sa "mula sa menu ng mensahe"). Ang webhook na may trigger_when na 2 ay hindi kailangan ng trigger words at kailangan ng display_name. I-upload ang icon nito gamit ang POST /api/v4/hooks/outgoing/{hook_id}/icon (multipart, field image: PNG, JPEG o GIF, na tinatago bilang 128 px PNG); ang icon_url nito ay tumutukoy sa GET /api/v4/hooks/outgoing/{hook_id}/icon.

Kung nasa pribadong network ang iyong service, dapat pahintulutan ng system admin ang address nito sa Pahintulutan ang mga untrusted internal connections sa (ServiceSettings.AllowedUntrustedInternalConnections). Hindi tinatawag ng server ang mga pribadong address kung wala ito.

Ang outgoing request

Ipinapadala ng Antimatter ang isang POST na may mga field na ito, bilang JSON o form-encoded depende sa 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": ""
}

Ihambing ang token sa token ng webhook bago gawin ang anumang bagay. Sa form-encoded na bersyon, ang timestamp ay nasa segundo hindi sa millisecond. Hihintayin ng server ang iyong sagot hangga't hihintayin ng Integration request timeout (30 segundo ang default, ServiceSettings.OutgoingIntegrationRequestsTimeout).

Sumagot sa isang outgoing webhook

Para mag-post ng sagot, sagutin gamit ang JSON. Para hindi mag-post ng anumang bagay, sagutin gamit ang empty body.

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

text at attachments: ang sagot. Kung wala ang alinman, hindi magkakaroon ng post.
response_type: ang comment ay nagpo-post ng sagot sa thread ng trigger message; kung hindi, ito ay pumapasok sa channel.
username, icon_url: ipapakita kapag pinapayagan ng server ang mga override; kung hindi, gagamitin ang sariling values ng webhook.
props, type, priority: katulad ng sa mga incoming webhook.

Ang sagot ay nagpo-post bilang tagapaglikha ng webhook, sa ilalim ng overridden na pangalan kung mayroon. Para sa anumang mas mahaba kaysa mabilis na sagot, sagutin agad at mag-post nang huli gamit ang incoming webhook o ang API.

Mga aksyon sa mensahe

Ang aksyon sa mensahe ay isang outgoing webhook na may Paggamit ng trigger words na nakatakda sa Mula sa menu ng mensahe. Hindi ito nag-activate sa mga ipinost na mensahe. Sa halip, nakikita ito ng mga tao sa menu ng mensahe: Mga aksyon sa mensahe (⋯) › Mga Karagdagang Aksyon, sa ilalim ng pamagat na Mga Integration, na may icon nito. Ang klasikong interface ay hindi nagpapakita ng mga aksyon sa mensahe. Kapag pinili ito, ipinapadala ang iisang mensahong iyon sa mga callback URL, at may maikling abiso na nagsasabi na Ipinadala sa pangalan ng aksyon, o ipinapakita ang iyong ephemeral_text.

Saan ito ipinapakita: sa channel ng webhook, o, kung wala sa channel, sa bawat pampublikong channel ng kanyang community. Ang mga pampublikong channel lamang ang may mga aksyon sa mensahe.
Ang mga Bisita ay nakakakuha lamang ng mga aksyon na nakabind sa channel na sila ay nasa loob, hindi ang mga community-wide.
Mga archived at read-only na channel: maa pa ring ipadala ang mensahe. Kapag na-archive ang isang channel, tinatanggal ang mga webhook na nakabind dito, kaya ang archived channel ay nagpapatuloy lamang sa mga community-wide na aksyon. Ang sagot na hindi nila maaaring ipost doon ay ipinapakita sa kanila lamang.
Rate limit: bawat tao ay maaaring gumamit ng 10 na aksyon sa mensahe bawat minuto, pagkatapos ng burst ng 5. Kung lumampas dito, sagot ng server ay 429.
Pribadong network: katulad ng ibang outgoing webhooks, dapat pahintulutan ang mga internal na address sa Pahintulutan ang mga untrusted internal connections sa.

Ang request

Ipinapadala ang payload bilang JSON o form-encoded, ayon sa content type ng 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
}

Ang user_id at user_name ay ang tao na pumili ng aksyon; ang post_user_id at post_user_name ay ang may-akda ng mensahe.
Ang iisang mensahong iyon lamang ang ipinapadala, hindi ang natitira ng thread nito.
Ang files ay nakalista ang mga file ng mensahe lamang kung ang tao na pumili ng aksyon ay maaaring i-download ang mga ito. Ang pag-download ng link ay nangangailangan ng session o token, katulad ng anumang file ng API.
Ang burn-on-read message ay ipinapadala nang walang teksto at mga file, na may burn_on_read na nakatakda sa true.
Sa form-encoded, ang mga file ay dumating bilang paulit-ulit na file_id, file_name, at file_link fields, sa parehong pagkakasunod.

Ang sagot

Ang sagot ay katulad ng anumang outgoing webhook (tingnan ang Reply to an outgoing webhook): ang text o attachments ay nagpo-post ng sagot sa channel, at ang "response_type": "comment" ay nagpo-post nito sa thread ng mensahe. Maaari ring sagutin gamit ang ephemeral_text (pinuputol sa 300 na karakter): ito ay ipapakita sa tao lamang na pumili ng aksyon, sa notisikasyon. Ang walang laman na body ay hindi nagpo-post ng anumang bagay.

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

Gamit ang API

GET /api/v4/channels/{channel_id}/message_actions: ang mga aksyon na maaari mong piliin sa isang channel, na may id, display_name, description, at icon_url. Walang naaalis na tokens o callback URLs.
POST /api/v4/posts/{post_id}/message_actions/{hook_id}: nagpapatakbo ng aksyon sa isang mensahe na maaari mong basahin. Ito ay sumasagot ng {"ephemeral_text"}.

Kapag hindi gumagana ang webhook

501 mula sa hook URL: patay ang mga incoming webhook sa server.
400 "Failed to decode the payload…": hindi valid ang JSON, o hindi tinatawag na payload ang form field. Ang "No text specified." ay nangangahulugang wala sa request ang text o attachments.
403: naka-lock ang webhook sa ibang channel, o hindi na mababasa ng kanyang may-ari ang channel.
Hindi kailanman tumitigil ang outgoing webhook: ang channel ay pribado, ang trigger ay hindi ang unang salita, ang mensahe ay mula sa isang webhook, o ang webhook ay nakatakda na tumigil mula sa From the message menu.
Hindi nasa menu ang isang message action: ang channel ay pribado, ang aksyon ay nakabind sa ibang channel, ang tao ay bisita at walang channel ang aksyon, o ang outgoing webhooks ay patay.
404 kapag nagpapatakbo ng message action: hindi umiiral ang aksyon, o hindi ito sumasakop sa channel ng mensahe para sa tao na iyon. 429: ang tao ay nagpatakbo ng higit sa 10 na aksyon sa loob ng isang minuto. 502: hindi maabot ang alinman sa mga callback URLs (nasa log ang dahilan).
Mga Log: kapag naka-on ang Paganahin ang Webhook Debugging (LogSettings.EnableWebhookDebugging) at nasa DEBUG ang log level, naglala-log ang server ng mga payload ng mga nabigong incoming requests. Ang mga nabigong outgoing calls ay nalala-log bilang Outgoing Webhook POST failed.