Webhookok

A bejövő webhook lehetővé teszi, hogy egy másik rendszer JSON-t küldjön egy titkos URL-címre, így üzenetet küldhessen egy csatornába. A kimenő webhook a fordítottját végzi: az Ön URL-címére küldi azokat az üzeneteket, amelyek egy kiváltószóval kezdődnek, vagy amelyeket a felhasználók a üzenetmenüből választanak, majd a válaszát is beküldi.

A webhookok kezelése

Nyisd meg az avatart a jobb felső sarokban, majd válaszd az Integrációk menüpontot. A jelenlegi közösség integrációs oldalaiban találod a Bejövő webhookok és a Kimenő webhookok listát. Minden webhook egyetlen közösséghez tartozik.

Alapértelmezés szerint a közösségi adminisztrátorok és a rendszeradminisztrátorok hozhatnak létre webhorgokat. A rendszeradminisztrátor jogosíthat fel más szerepköröket is a Rendszerkonzol jogosultság-beállításaiban. A rendszeradminisztrátor kikapcsolhatja az egyes típusokat a Rendszerkonzol › Integrációk › Integrációkezelés menüben: a Bejövő webhorgok engedélyezése és a Kimenő webhorgok engedélyezése alapértelmezés szerint bekapcsolva van.

Bejövő webhook létrehozása

1. Az Integrációk menüben válaszd a Bejövő webhookok lehetőséget, majd kattints az Bejövő webhook hozzáadása gombra.
2. Töltsd ki a Cím és a Leírás mezőket: ezek csak az integrációs oldalakon jelennek meg.
3. Válaszd ki azt a Csatornát, ahová az üzenetek alapértelmezés szerint kerülnek. Privát csatorna esetén annak tagjának kell lenned.
4. Jelölje be a Hozzákötés ehhez a csatornához lehetőséget, ha a küldők nem küldhetnek máshová.
5. Opcionálisan állítsa be a Felhasználónév és a Profilkép URL-címét az üzeneteihez (lásd Név és ikon).
6. Válaszd a Mentés lehetőséget. Másold ki a megjelenített URL-t: https://chat.example.com/hooks/<key>.

API-val: POST /api/v4/hooks/incoming a következő testtel: {"channel_id", "display_name", "description", "username", "icon_url", "channel_locked"}; a válasz id mezője a kulcs. Parancssorból: amctl webhook create-incoming --channel <channel id> --user <user> --display-name "CI".

Üzenet küldése egy bejövő webhookba

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

A szerver 200 státusszal és ok testtel válaszol. Elfogadja az application/x-www-form-urlencoded formátumot is, ahol a JSON egy payload mezőben van, ahogy a Slack webhookjai is teszik, így a Slackhoz készült eszközök általában változtatás nélkül működnek.

Minden webhook által küldött üzenet mellett a neve mellett megjelenik a BOT jelölés, még akkor is, ha a létrehozó nevével jelenik meg, így a felhasználók megkülönböztethetik a valódi személyek üzeneteitől. A webhook üzenetek soha nem indítanak kimenő webhorgokat.

Név és ikon

A webhook a létrehozója nevében publikál, hacsak a szerver nem engedi a felülírásokat. Két beállítás a Rendszerkonzol › Integrációk › Integrációkezelés menüpontban, mindkettő alapértelmezetten kikapcsolva, ezt módosítja:

• Engedélyezze az integrációkat a felhasználónevek felülírására (ServiceSettings.EnablePostUsernameOverride): a webhook Felhasználóneve vagy a kérés username mezője jelenik meg; ha egyik sincs megadva, a név webhook lesz.
• Integrációk engedélyezése profilképek felülírásához (ServiceSettings.EnablePostIconOverride): a webhook Profilképe, vagy a kérés icon_url vagy icon_emoji mezője jelenik meg.

A kérésben megadott érték felülírja a webhookon tárolt értéket.

Csatolmányok

A csatolmányok strukturált tartalmat adnak a szöveg alá. A Slack üzenet-csatolmány-formátumát követik:

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

Kártyák: fázisok és diagramok

Az Antimatter két mezőt ad hozzá a csatolmányokhoz, amelyeket az alapértelmezett felület megjelenít:

• stages: egy pipeline lépései pill formában, legfeljebb 20 darab. Mindegyik {"name", "status"} formátumú, ahol a statusz értéke passed, failed, running, pending, skipped vagy canceled lehet.
• chart: a közelmúlti értékeket ábrázoló kis vonaldiagram, {"values": [2 to 200 numbers], "threshold": number, "label": "…"}. A küszöbérték szaggatott vonalként jelenik meg, és jelzi a riasztás határértékét.

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

A klasszikus felület és a többi kliens figyelmen kívül hagyja ezeket a két mezőt, ezért a lényeget a text vagy fields mezőbe is érdemes felvenni.

Kimenő webhook létrehozása

A kimenő webhook figyel a közösség Nyilvános csatornáin. Üzenetet küld a megadott URL címre, ha az üzenet első szava megegyezik valamelyik kulcsszavával, vagy ha valaki kiválasztja az üzenet menüjéből (ez egy üzenetművelet).

1. Az Integrációk menüpontban válassza a Kimenő webhookok lehetőséget, majd kattintson a Kimenő webhook hozzáadása gombra.
2. Töltse ki a Cím és a Leírás mezőket.
3. Válassza ki a kérés Tartalomtípusát: application/x-www-form-urlencoded vagy application/json.
4. Válasszon egy Csatornat, adjon meg Kulcsszavak (soronként egy)-t, vagy mindkettőt. Ha csatornát választ, de nem ad meg kulcsszavakat, akkor a csatorna minden üzenete elküldésre kerül. Ha mindkettőt megadja, az üzenetnek mindkét feltételnek meg kell felelnie.
5. Az Aktiválás amikor mezőnél válassza az Az első szó pontosan megfelel egy kulcsszónak, az Az első szó egy kulcsszóval kezdődik vagy a Az üzenet menüjéből lehetőséget. Ha az Az üzenet menüjéből opciót választja, a kulcsszavak mező eltűnik, a Csatorna mező opcionális (ha nem ad meg csatornát, a művelet a közösség minden nyilvános csatornájában elérhető lesz), és a Cím mező kötelező: ez a művelet neve a menüben.
6. Adja meg a Visszahívás URL-ek (Soronként egy). Minden megadott URL cím megkapja a feltételeknek megfelelő üzeneteket.
7. Opcionálisan állítsa be a Felhasználónév és a Profilkép mezőket, amelyeket a válaszokhoz használnak. Az üzenet menüjéből indított műveleteknél az Ikona mező helyettesíti a Profilkép mezőt: egy .png vagy .jpg kép URL címe, vagy az Antimatter alapértelmezett felületén egy feltöltött kép. A menü szürke színnel jeleníti meg; ha nincs megadva, a művelet egy semleges ikont kap.
8. Kattintson a Mentés gombra, és másolja ki a megjelenített tokent. A szolgáltatása ezt használja annak ellenőrzésére, hogy a kérések a szerverétől származnak.

API-val: POST /api/v4/hooks/outgoing a következő testtel: {"team_id", "channel_id", "trigger_words", "trigger_when", "callback_urls", "content_type", "display_name"} (a trigger_when értéke: 0 pontos egyezéshez, 1 „kezdődik”-hez, 2 „az üzenet menüjéből”-hez). A trigger_when érték 2-vel rendelkező webhook nem fogad el kulcsszavakat, és megköveteli a display_name mezőt. Az ikonját a POST /api/v4/hooks/outgoing/{hook_id}/icon kéréssel töltheti fel (multipart, image mező: PNG, JPEG vagy GIF, 128 px-es PNG-ként tárolva); ekkor a icon_url mező a GET /api/v4/hooks/outgoing/{hook_id}/icon címre mutat.

A kimenő kérés

Az Antimatter POST kérést küld az alábbi mezőkkel, JSON vagy form-encoded formátumban a tartalomtípus függvényében:

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

Minden más előtt hasonlítsa össze a token értékét a webhook tokenjével. A form-encoded változatban a timestamp másodpercben, nem milliszekundumban van megadva. A szerver addig vár a válaszra, amíg az Integrációs kérés időtúllépési határa (alapértelmezés szerint 30 másodperc, ServiceSettings.OutgoingIntegrationRequestsTimeout) engedi.

Válasz küldése egy kimenő webhookra

Válasz küldéséhez JSON formátumban kell válaszolni. Ha nem szeretnél semmit sem küldeni, üres testtel válaszolj.

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

• text és attachments: a válasz tartalma. Ha egyik sem van meg, nem kerül semmi publikálásra.
• response_type: a comment értékkel a válasz a kiváltó üzenet üzenetszálába kerül; más esetben a csatornába.
• username, icon_url: akkor jelennek meg, ha a szerver engedélyezi a felülírásokat; különben a webhook saját értékei kerülnek használatba.
• props, type, priority: ugyanazok, mint a bejövő webhookoknál.

A válasz a webhook létrehozójaként kerül publikálásra, a felülírt névvel, ha van ilyen. Ha a válasz hosszabb, mint egy rövid megjegyzés, azonnal küldd el, majd később publikáld bejövő webhookkal vagy az API-val.

Üzenetműveletek

Az üzenet művelet egy kimenő webhook, amelynek Aktiválás amikor beállítása Az üzenet menüjéből értékre van állítva. Soha nem aktiválódik a beküldött üzeneteknél. Ehelyett az emberek az üzenet menüjében látják: Üzenet műveletek (⋯) › További műveletek, az Integrációk fejezet alatt, a saját ikonjával. A klasszikus felület nem jeleníti meg az üzenet műveleteket. A kiválasztásakor az adott üzenet elküldésre kerül a visszahívási URL-ekre, és egy rövid értesítés megjelenik, amely a Küldve ide szöveget és a művelet nevét, vagy a ephemeral_text értékét mutatja.

• Megjelenési helye: a webhook csatornájában, vagy, ha nincs csatorna, a közösség minden nyílt csatornájában. Csak a nyílt csatornák rendelkeznek üzenet műveletekkel.
• A Vendégek csak azokat a műveleteket kapják, amelyekhez csatlakoztatott csatornában vannak, nem pedig a közösségi szintűeket.
• Archivált és csak olvasható csatornák: az üzenet továbbra is elküldhető. Egy csatorna archiválása során törlődnek a hozzá csatolt webhooks, így egy archivált csatorna csak a közösségi szintű műveleteket őrzi. Ha a válasz nem küldhető el oda, ahol a felhasználó nem posztolhat, az csak neki jelenik meg.
• Sebességkorlát: minden felhasználó percben 10 üzenet műveletet futtathat, 5-ös burst után. Ezen felül a szerver 429 kóddal válaszol.
• Privát hálózatok: más kimenő webhooksokhoz hasonlóan, a belső címeket engedélyezni kell a Nem megbízható belső kapcsolatok engedélyezése ide beállításban.

A kérés

A terhelés (payload) JSON vagy form-encoded formátumban küldődik, a webhook tartalomtípusa szerint:

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

• A user_id és user_name azt a személyt jelöli, aki kiválasztotta a műveletet; a post_user_id és post_user_name pedig az üzenet szerzőjét.
• Csak az adott üzenet kerül elküldésre, soha nem a teljes üzenetszál.
• A files mező csak akkor sorolja fel az üzenet fájloit, ha a műveletet kiválasztó felhasználó letöltheti őket. A link letöltéséhez session vagy token szükséges, mint az API bármely fájljánál.
• A „olvastáskor elpusztuló” (burn-on-read) üzenet szövege és fájloinak nélkül küldődik, a burn_on_read értékére true állítva.
• Form-kódolt formátumban a fájlok ismétlődő file_id, file_name és file_link mezőként érkeznek, ugyanabban a sorrendben.

A válasz

A válasz bármely kimenő webhook esetén (lásd: Válasz egy kimenő webhookra): a text vagy attachments mező egy választ küld a csatornába, a "response_type": "comment" pedig az üzenet szálába. Válaszolni lehet ephemeral_text mezővel is (300 karakterig): ez csak az illetőnek jelenik meg, a bejelentésben. Ha a válasz test része üres, semmi sem kerül bejegyzésre.

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

Az API-val

• GET /api/v4/channels/{channel_id}/message_actions: a csatornában választható műveletek, id, display_name, description és icon_url mezőkkel. Sem tokeneket, sem visszahívási URL-eket nem ad vissza.
• POST /api/v4/posts/{post_id}/message_actions/{hook_id}: lefuttat egy műveletet egy olyan üzeneten, amelyhez hozzáférhetsz. A válasz {"ephemeral_text"}.

Ha egy webhook nem működik

• 501 hiba a webhook URL-jéből: a bejövő webhookok kikapcsolva vannak a szerveren.
• 400 "Failed to decode the payload…": a JSON érvénytelen, vagy a form mező neve nem payload. A "No text specified." hibaüzenet azt jelenti, hogy a kérésben nincs text és attachments mező sem.
• 403: a webhook egy másik csatornára van rögzítve, vagy a tulajdonosa már nem olvashatja a csatornát.
• Egy kimenő webhook soha nem indul el: a csatorna privát, a kiváltó szó nem az első szó, az üzenet egy webhooktól származott, vagy a webhook Az üzenet menüjéből kiváltásra van beállítva.
• Egy üzenetművelet nem szerepel a menüben: a csatorna privát, a művelet egy másik csatornához van kötve, a felhasználó vendég, és a művelet nem rendelkezik csatornához, vagy a kimenő webhooks kikapcsolva vannak.
• 404 hiba egy üzenetművelet futtatásakor: a művelet nem létezik, vagy nem vonatkozik az adott felhasználó számára az üzenet csatornájára. 429: a felhasználó több mint 10 műveletet futtatott egy perc alatt. 502: egyik visszahívási URL-re sem lehetett csatlakozni (a naplóban szerepel az ok).
• Naplók: ha a Webhook hibakeresés engedélyezése be van kapcsolva (LogSettings.EnableWebhookDebugging), és a naplószint DEBUG, a szerver naplózza a sikertelen bejövő kérések terhelését. A sikertelen kimenő hívások Outgoing Webhook POST failed néven kerülnek naplóba.