Webhookit

Saapuva webhook mahdollistaa toisen järjestelmän viestinnän kanavalle lähettämällä JSON-muotoista dataa salaiseen URL-osoitteeseen. Lähtevä webhook tekee päinvastoin: se lähettää viestit URL-osoitteeseesi, joko ne, jotka alkavat laukaisusanalla, tai ne, jotka käyttäjä valitsee viestivalikosta, ja julkaisee antamasi vastauksen.

Webhookkien hallinta

Avaa tiimivalikko, valitse Tiimin asetukset ja klikkaa Integraatiot välilehtien lopussa. Nykyisen tiimin integraatiosivut sisältävät Saapuvat Webhookit ja Lähtevät webhooks. Jokainen webhook kuuluu yhteen tiimiin.

Oletusarvoisesti tiimin ylläpitäjät ja järjestelmän ylläpitäjät voivat luoda webhookkeja. Järjestelmän ylläpitäjä voi myöntää oikeuden muille rooleille Järjestelmäkonsolin käyttöoikeusasetuksissa. Järjestelmän ylläpitäjä voi myös kytkeä kummankin tyypin pois päältä kohdassa Järjestelmäkonsoli › Integraatiot › Integraatioiden hallinta: Ota vastaanottavat webhookit käyttöön ja Ota lähtevät webhookit käyttöön ovat oletuksena päällä.

Saapuvan webhokin luominen

1. Valitse Integraatiot -välilehdeltä Saapuvat webhookit ja sen jälkeen Lisää saapuva webhook.
2. Täytä Otsikko ja Kuvaus: ne näkyvät vain integraatioiden sivuilla.
3. Valitse Kanava, johon viestit lähetetään oletuksena. Yksityisen kanavan tapauksessa sinun on oltava sen jäsen.
4. Valitse Lukitse tähän kanavaan, jos lähettäjien ei sallita lähettää muualle.
5. Aseta valinnaisesti Käyttäjätunnus ja Profiilikuva-URL viesteille (katso Nimi ja ikoni).
6. Valitse Tallenna. Kopioi näytetty URL-osoite: https://chat.example.com/hooks/<key>.

API:lla: POST /api/v4/hooks/incoming kuormalla {"channel_id", "display_name", "description", "username", "icon_url", "channel_locked"}; vastauksen id on avain. Komentoriviltä: amctl webhook create-incoming --channel <channel id> --user <user> --display-name "CI".

Viestin lähettäminen saapuvaan webhookiin

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

Palvelin vastaa 200 ruumiilla ok. Se hyväksyy myös application/x-www-form-urlencoded -muodon, jossa JSON on payload -kentässä, kuten Slackin webhookit, joten Slackille tehdyt työkalut toimivat yleensä muuttumattomina.

Jokaisessa webhookin julkaisemassa viestissä on BOTTI-merkintä nimen vieressä, vaikka viesti näkyisi tekijän nimellä, jotta ihmiset erottavat sen oikean henkilön viestistä. Webhook-viestit eivät koskaan laukaise lähteviä webhookkeja.

Nimi ja ikoni

Webhook julkaisee viestin sen luoneen henkilön nimissä, ellei palvelin salli yliaukkoja. Kaksi asetuusta kohdassa Järjestelmäkonsoli › Integraatiot › Integraatioiden hallinta, jotka ovat oletusarvoisesti poissa käytöstä, muuttavat tätä:

• Salli integraatioiden yliajaa käyttäjätunnukset (ServiceSettings.EnablePostUsernameOverride): webhoonin Käyttäjätunnus tai pyynnön username näytetään sen sijaan; jos kumpikaan ei ole asetettu, nimi on webhook.
• Salli integraatioiden yliajaa profiilikuvakkeet (ServiceSettings.EnablePostIconOverride): webhoonin Profiilikuva tai pyynnön icon_url tai icon_emoji näytetään.

Pyynnön arvo voittaa webhooken tallennetun arvon.

Liitteet

Liitteet lisäävät strukturoitua sisältöä tekstin alle. Ne noudattavat Slackin viestiliiteformaatia:

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

Kortit: vaiheet ja kaaviot

Antimatter lisää liitteisiin kaksi kenttää, jotka oletuskäyttöliittymä piirtää:

• stages: putken vaiheet pillien muodossa, enintään 20. Jokainen on {"name", "status"}, ja tila on passed, failed, running, pending, skipped tai canceled.
• chart: pieni viivakaavio viimeaikaisista arvoista, {"values": [2 to 200 numbers], "threshold": number, "label": "…"}. Rajan arvo piirretään katkoviivana, esimerkiksi hälytysrajan visualisoimiseksi.

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

Klassinen käyttöliittymä ja muut asiakasohjelmat ignoroi nämä kaksi kenttää, joten lisää olennainen tieto myös text- tai fields-kenttään.

Luo lähtevä webhook

Lähtevä webhook seuraa tiimin julkisia kanavia. Se lähettää viestin URL-osoitteeseesi joko kun viestin ensimmäinen sana vastaa yhtä sen laukaisusanoista, tai kun joku valitsee sen viestin valikosta (viestitoiminto).

1. Valitse Integraatiot -välilehdeltä Lähtevät webhooks ja sen jälkeen Lisää lähtevä webhook.
2. Täytä Otsikko ja Kuvaus.
3. Valitse pyynnön Sisällontyyppi: application/x-www-form-urlencoded tai application/json.
4. Valitse Kanava, syötä Laukaisusanat (yksi per rivi) tai molemmat. Jos valitset kanavan ilman laukaisusanoja, kaikki kanavan viestit lähetetään. Jos valitset molemmat, viestin on täytettävä molemmat ehdot.
5. Valitse kohdassa Laukaisu, kun vaihtoehdoista Ensimmäinen sana vastaa laukaisusanaa täsmälleen, Ensimmäinen sana alkaa laukaisusanalla tai Viestin valikosta. Kun valitset Viestin valikosta, laukaisusanat poistuvat, Kanava on valinnainen (jos kanavaa ei ole määritetty, toiminto tarjotaan kaikissa yhteisön julkisissa kanavissa) ja Otsikko on pakollinen: se on toiminnon nimi valikossa.
6. Syötä Callback-URL:it (yksi per rivi). Jokainen URL saa jokaisen vastaavan viestin.
7. Voit halutessasi määrittää vastauksissa käytettävän Käyttäjätunnuksen ja Profiilikuvan. Viestin valikosta käynnistettävien toimintojen kohdalla Kuvake-kenttä korvaa Profiilikuvan: kenttään syötetään .png- tai .jpg-kuvan URL-osoite tai, Antimatterin oletuskäyttöliittymässä, ladattu kuva. Valikossa kuvake näkyy harmaana; jos kuvaketta ei ole määritetty, toiminto saa neutraalin kuvakkeen.
8. Valitse Tallenna ja kopioi näytetty token. Palvelusi käyttää sitä varmistaakseen, että pyynnöt tulevat palvelimeltasi.

Käyttämällä API:a: POST /api/v4/hooks/outgoing ja {"team_id", "channel_id", "trigger_words", "trigger_when", "callback_urls", "content_type", "display_name"} (trigger_when: 0 täydellistä vastaavuutta varten, 1 "alkaa sanalla" -vastaavuutta varten, 2 "viestin valikosta" -käynnistystä varten). Webhook, jossa trigger_when on 2, ei käytä laukaisusanoja ja vaatii display_name-arvon. Lataa sen kuvake komennolla POST /api/v4/hooks/outgoing/{hook_id}/icon (multipart, kenttä image: PNG, JPEG tai GIF, tallennetaan 128 px:n PNG-kuvana); sen icon_url osoittaa tällöin osoitteeseen GET /api/v4/hooks/outgoing/{hook_id}/icon.

Lähtevä pyyntö

Antimatter lähettää POST-pyynnön, jossa on nämä kentät JSON- tai lomakekoodattuna sisällön tyypin mukaan:

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

Vertaa token-arvo webhooken tokeniin ennen minkään tekemistä. Lomakekoodatussa versiossa timestamp on sekunteina, ei millisekunteina. Palvelin odottaa vastaustasi niin kauan kuin Integraatiopyyntöjen aikakatkaisu sallii (oletusarvo 30 sekuntia, ServiceSettings.OutgoingIntegrationRequestsTimeout).

Vastaa lähtevään webhooken

Julkistaaksesi vastauksen, vastaa JSON:lla. Jos et halua julkaista mitään, vastaa tyhjällä ruumiilla.

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

• text ja attachments: vastaus. Jos kumpikaan ei ole mukana, mitään ei julkaista.
• response_type: comment julkistaa vastauksen alkuperäisen viestin ketjuun; muuten se julkaistaan kanavaan.
• username, icon_url: näytetään, jos palvelin sallii yliajojen; muuten käytetään webhooken omia arvoja.
• props, type, priority: kuten lähtevissä webhookeissa.

Vastaus julkaistaan webhooken luojaan nimettynä, jos yliajo on määritetty. Jos vastaus on pidempi kuin lyhyt kommentti, vastaa heti ja julkista myöhemmin lähtevän webhooken tai API:n kautta.

Viestitoiminnot

Viestitoiminto on ulostuleva webhook, jossa Laukaisu, kun on asetettu arvoon Viestin valikosta. Se ei koskaan käynnisty lähetetyistä viesteistä. Sen sijaan ihmiset näkevät sen viestin valikossa: Viestitoiminnot (⋯) › Lisätoiminnot Integraatiot-otsikon alla kuvakkeineen. Klassinen käyttöliittymä ei näytä viestitoimintoja. Kun valitset toiminnon, kyseinen viesti lähetetään callback-URL-osoitteisiin, ja lyhyt ilmoitus kertoo Lähetetty toiminnon nimellä tai näyttää ephemeral_text-arvosi.

• Missä se näkyy: webhookin kanavassa tai, jos kanavaa ei ole määritetty, kaikissa sen yhteisön julkisissa kanavissa. Vain julkisissa kanavissa on viestitoimintoja.
• Vieraat saavat vain niihin kanaviin sidotut toiminnot, joissa he ovat, eivät yhteisön laajuisia toimintoja.
• Arkistoidut ja vain luku -tilassa olevat kanavat: viesti voidaan silti lähettää. Kanavan arkistointi poistaa siihen sidotut webhookit, joten arkistoidussa kanavassa säilyvät vain yhteisön laajuiset toiminnot. Vastaus, jota henkilö ei voinut lähettää sinne, näytetään vain hänelle.
• Rajoitus: kukin henkilö voi suorittaa 10 viestitoimintoa minuutissa, 5 toiminnon alkurynnäköstä huolimatta. Tämän ylittävien pyyntöjen kohdalla palvelin vastaa 429.
• Yksityiset verkot: kuten muiden lähtevien webhookien kohdalla, sisäisten osoitteiden on oltava sallittuja asetuksessa Salli luottamattomat sisäiset yhteydet osoitteisiin.

Pyyntö

Tietosisältö lähetetään JSON-muodossa tai lomakkeena koodattuna webhookin sisältötyypin mukaisesti:

{
  "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 ja user_name ovat toiminnon valinneen henkilön tiedot; post_user_id ja post_user_name ovat viestin kirjoittajan tiedot.
• Vain kyseinen viesti lähetetään, ei sen ketjun muita viestejä.
• files sisältää viestin tiedostot vain, jos toiminnon valinnut henkilö voi ladata ne. link-osoitteen lataaminen vaatii istunnon tai tunnuksen, kuten kaikki muutkin API:n tiedostot.
• Kertaluenteinen viesti lähetetään ilman tekstiä ja tiedostoja, ja burn_on_read on asetettu arvoon true.
• Lomakkeena koodattuna tiedostot lähetetään toistuvina file_id-, file_name- ja file_link-kenttinä samassa järjestyksessä.

Vastaus

Vastaa kuten minkä tahansa lähtevän webhookin kohdalla (katso Vastaa lähtevään webhookiin): text tai attachments julkaisee vastauksen kanavalla, ja "response_type": "comment" julkaisee sen viestin ketjussa. Voit myös vastata käyttämällä ephemeral_text-kenttää (katkaistaan 300 merkkiin): se näytetään vain toiminnon valinneelle henkilölle ilmoituksessa. Tyhjä tietosisältö ei julkaise mitään.

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

API:n avulla

• GET /api/v4/channels/{channel_id}/message_actions: kanavalla valittavissa olevat toiminnot, joihin kuuluvat id, display_name, description ja icon_url. Tokeneita tai callback-URL-osoitteita ei palauteta.
• POST /api/v4/posts/{post_id}/message_actions/{hook_id}: suorittaa toiminnon viestissä, jonka voit lukea. Vastauksena palautetaan {"ephemeral_text"}.

Kun webhook ei toimi

• 501 webhooken URL:stä: lähtevät webhookit on poistettu käytöstä palvelimella.
• 400 "Failed to decode the payload…": JSON on virheellinen, tai lomakekentän nimi ei ole payload. "No text specified." tarkoittaa, että pyynnössä ei ole text- eikä attachments-kenttää.
• 403: webhook on lukittu toiseen kanavaan, tai sen omistaja ei enää voi lukea kanavaa.
• Lähtevä webhook ei koskaan laukaise: kanava on yksityinen, laukaisinsana ei ole viestin ensimmäinen sana, viesti on peräisin webhookista tai webhook on asetettu laukeamaan Viestin valikosta.
• Viestitoiminto ei näy valikossa: kanava on yksityinen, toiminto on sidottu toiseen kanavaan, henkilö on vieras eikä toiminnolla ole kanavaa, tai lähtevät webhookit on poistettu käytöstä.
• 404 virhe viestitoimintoa suoritettaessa: toimintoa ei ole olemassa, tai se ei kata kyseisen henkilön kanavaa kyseiselle viestille. 429: henkilö suoritti yli 10 toimintoa minuutissa. 502: yhtäkään callback-URL-osoitetta ei voitu tavoittaa (loki sisältää syyn).
• Viestin lähettäminen foorumille hylätään: webhookin viesti vaatii otsikon (props.am_thread_title). Virhe kertoo syyn, kuten app.post.forum.title_required.app_error, yleisen virheen sijaan (katso Kanavat).
• Lokit: kun Ota käyttöön webhook-vianhaku on päällä (LogSettings.EnableWebhookDebugging) ja lokitaso on DEBUG, palvelin lokiittaa epäonnistuneiden saapuvien pyyntöjen kuormat. Epäonnistuneet lähetyskutsut lokitoidaan tekstillä Outgoing Webhook POST failed.