Webhooks

En innkommende webhook lar et annet system poste i en kanal ved å sende JSON til en hemmelig URL. En utgående webhook gjør det motsatte: den sender meldinger til din URL, enten de starter med et utløserord, eller noen velger dem i meldingsmenyen, og poster det du svarer.

Hvor du administrerer webhooks

Åpne avataren øverst til høyre, deretter Integrasjoner. Integrasjonssidene i den aktuelle communityen viser Innkommende webhooks og Utgående webhooks. Hver webhook tilhører én community.

Som standard kan community-administratorer og systemadministratorer opprette webhooks. En systemadministrator kan gi rettighetene til andre roller i tillatelsesinnstillingene i Systemkonsollen. En systemadministrator kan også slå av hver type i Systemkonsoll › Integrasjoner › Integrasjonsadministrasjon: Aktiver innkommende webhooks og Aktiver utgående webhooks er begge på som standard.

Lag en innkommende webhook

1. I Integrasjoner, velg Innkommende webhooks, deretter Legg til innkommende webhook.
2. Fyll inn en Tittel og en Beskrivelse: de vises bare på integrasjonssidene.
3. Velg Kanal som meldingene skal til som standard. For en privat kanal må du være medlem av den.
4. Bok avkrysningsfeltet Lås til denne kanalen hvis avsendere ikke skal kunne poste andre steder.
5. Vil du, kan du angi et Brukernavn og en Profilbilde-URL for meldingene (se Navn og ikon).
6. Velg Lagre. Kopier den viste URL-en: https://chat.example.com/hooks/<key>.

Med API-et: POST /api/v4/hooks/incoming med {"channel_id", "display_name", "description", "username", "icon_url", "channel_locked"}; svarets id er nøkkelen. Fra kommandolinjen: amctl webhook create-incoming --channel <channel id> --user <user> --display-name "CI".

Send en melding til en innkommende 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:"}'

Serveren svarer med 200 og kroppen ok. Den godtar også application/x-www-form-urlencoded med JSON-et i et payload-felt, slik Slacks webhooks gjør, så verktøy laget for Slack fungerer vanligvis uendret.

Hver melding en webhook poster har et BOT-merke ved siden av navnet, selv når den vises under skaperens navn, slik at folk kan skille den fra en ekte persons melding. Webhook-meldinger utløser aldri utgående webhooks.

Navn og ikon

En webhook poster som personen som opprettet den, med mindre serveren tillater overstyring. To innstillinger i Systemkonsoll › Integrasjoner › Integrasjonsadministrasjon, begge av som standard, endrer dette:

• Aktiver integrasjoner som skal overstyre brukernavn (ServiceSettings.EnablePostUsernameOverride): webhookens Brukernavn eller forespørelsens username vises i stedet; uten noen av dem, er navnet webhook.
• Aktiver at integrasjoner kan overskrive profilbildeikoner (ServiceSettings.EnablePostIconOverride): webhookens Profilbilde, eller forespørelsens icon_url eller icon_emoji, vises.

En verdi i forespørselen har forrang over den som er lagret på webhooken.

Vedlegg

Vedlegg legger til strukturert innhold under teksten. De følger Slacks meldingsvedleggsformat:

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

Kort: stadier og diagrammer

Antimatter legger til to felter i vedlegg, som vises av standardgrensesnittet:

• stages: trinnene i en pipeline som piller, opptil 20. Hvert trinn er {"name", "status"}, med en status som er passed, failed, running, pending, skipped eller canceled.
• chart: en liten linjediagram over nylige verdier, {"values": [2 to 200 numbers], "threshold": number, "label": "…"}. Terskelverdien tegnes som en strekete linje, for en varsels grense.

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

Det klassiske grensesnittet og andre klienter ignorerer disse to feltene, så legg også det viktigste i text eller fields.

Opprett en utgående webhook

En utgående webhook overvåker offentlige kanaler i et samfunn. Den sender en melding til din URL enten når meldingens første ord samsvarer med ett av utløserordene, eller når noen velger den i meldingens meny (en meldingshandling).

1. I Integrasjoner, velg Utgående webhooks, deretter Legg til utgående webhook.
2. Fyll inn Tittel og Beskrivelse.
3. Velg Innholdstype for forespørselen: application/x-www-form-urlencoded eller application/json.
4. Velg en Kanal, skriv inn Utløsende ord (ett per linje), eller begge deler. Med en kanal og ingen utløsende ord, sendes alle meldinger i den kanalen. Med begge, må meldingen matche begge.
5. Under Utløs når, velg Første ord samsvarer nøyaktig med et utløserord, Første ord starter med et utløserord, eller Fra meldingsmenyen. Med Fra meldingsmenyen forsvinner utløserordene, Kanal er valgfri (uten en, tilbys handlingen i alle offentlige kanaler i samfunnet), og Tittel er obligatorisk: det er handlingens navn i menyen.
6. Skriv inn Tilbakekall-URL-er (én per linje). Hver URL mottar alle meldinger som samsvarer.
7. Valgfritt kan du sette Brukernavn og Profilbilde som brukes for svar. For en handling fra meldingsmenyen erstatter Icon-feltet Profilbilde: URL-en til en .png- eller .jpg-bilde, eller, i Antimatters standardgrensesnitt, et lastet opp bilde. Meny viser det i grått; uten ett, får handlingen et nøytralt ikon.
8. Velg Lagre og kopier tokenet som vises. Tjenesten din bruker dette for å bekrefte at forespørsler kommer fra serveren din.

Med API-et: POST /api/v4/hooks/outgoing med {"team_id", "channel_id", "trigger_words", "trigger_when", "callback_urls", "content_type", "display_name"} (trigger_when: 0 for eksakt samsvar, 1 for «starter med», 2 for «fra meldingsmenyen»). En webhook med trigger_when 2 tar ikke imot utløsende ord, men krever et display_name. Last opp ikonet med POST /api/v4/hooks/outgoing/{hook_id}/icon (multipart, felt image: PNG, JPEG eller GIF, lagret som en 128 px PNG); icon_url peker da mot GET /api/v4/hooks/outgoing/{hook_id}/icon.

Den utgående forespørselen

Antimatter sender en POST med disse feltene, som JSON eller formularkodet avhengig av innholdstypen:

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

Sammenlign token med webhookens token før du gjør noe. I den formkodede versjonen er timestamp i sekunder i stedet for millisekunder. Serveren venter på svaret ditt så lenge Tidsavbrudd for integrasjonsforespørsler tillater (30 sekunder som standard, ServiceSettings.OutgoingIntegrationRequestsTimeout).

Svar til en utgående webhook

For å poste et svar, svar med JSON. For ikke å poste noe, svar med en tom 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 og attachments: svaret. Uten noe av disse, postes det ingenting.
• response_type: comment poster svaret i tråden til utløsende melding; ellers går det til kanalen.
• username, icon_url: vises når serveren tillater overskrivninger; webhookens egne verdier brukes ellers.
• props, type, priority: som for innkommende webhooks.

Svaret postes som webhookens oppretter, under det overskrevne navnet hvis det finnes. For noe lenger enn et raskt svar, svar umiddelbart og poster senere med en innkommende webhook eller API-et.

Meldingshandlinger

En meldingshandling er en utgående webhook med Utløs når satt til Fra meldingsmenyen. Den utløses aldri på sendte meldinger. I stedet ser brukere den i en meldings meny: Meldingshandlinger (⋯) › Flere handlinger, under overskriften Integrasjoner, med ikonet. Den klassiske grensesnittet viser ikke meldingshandlinger. Når du velger den, sendes den enkelte meldingen til callback-URL-ene, og en kort melding sier Sendt til handlingens navn, eller viser ephemeral_text din.

• Hvor den vises: i webhookens kanal, eller, uten en kanal, i alle offentlige kanaler i arbeidsområdet. Bare offentlige kanaler har meldingshandlinger.
• Gjester får kun handlingene som er bundet til en kanal de er i, ikke de som gjelder for hele arbeidsområdet.
• Arkiverte og skrivebeskyttede kanaler: meldingen kan fortsatt sendes. Når en kanal arkiveres, slettes webhookene som er bundet til den, så en arkivert kanal beholder kun handlingene som gjelder for hele arbeidsområdet. Et svar som personen ikke kunne poste i kanalen, vises kun for vedkommende.
• Rategrense: hver person kan kjøre 10 meldingshandlinger i minuttet, etter en burst på 5. Over dette svarer serveren med 429.
• Private nettverk: som for andre utgående webhooks, må interne adresser tillates i Tillat upålitelige interne tilkoblinger til.

Forespørselen

Dataoverføringen sendes som JSON eller formularkodet, avhengig av webhookens innholdstype:

{
  "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 og user_name er personen som valgte handlingen; post_user_id og post_user_name er forfatteren av meldingen.
• Bare den meldingen sendes, aldri resten av tråden.
• files lister meldingens filer bare hvis personen som valgte handlingen kan laste dem ned. For å laste ned en link kreves en økt eller en token, som for alle filer i API-et.
• En melding som brennes ved lesing sendes uten tekst og filer, med burn_on_read satt til true.
• Ved form-koding kommer filene som gjentatte file_id, file_name og file_link-felter, i samme rekkefølge.

Svaret

Svar som for enhver utgående webhook (se Svar på en utgående webhook): text eller attachments legger ut et svar i kanalen, og "response_type": "comment" legger det ut i meldingens tråd. Du kan også svare med ephemeral_text (kuttet til 300 tegn): det vises kun for personen som valgte handlingen, i varselet. En tom kropp legger ingenting ut.

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

Med API-et

• GET /api/v4/channels/{channel_id}/message_actions: handlingene du kan velge i en kanal, med id, display_name, description og icon_url. Verken token eller callback-URL-er returneres.
• POST /api/v4/posts/{post_id}/message_actions/{hook_id}: kjører en handling på en melding du kan lese. Den svarer med {"ephemeral_text"}.

Når en webhook ikke fungerer

• 501 fra hook-URL-en: innkommende webhooks er slått av på serveren.
• 400 "Failed to decode the payload…": JSON-en er ugyldig, eller formfeltet heter ikke payload. "No text specified." betyr at forespørselen verken har text eller attachments.
• 403: webhooken er låst til en annen kanal, eller eieren kan ikke lenger lese kanalen.
• En utgående webhook utløses aldri: kanalen er privat, utløseren er ikke det første ordet, meldingen kom fra en webhook, eller webhooken er satt til å utløses Fra meldingsmenyen.
• En meldingshandling er ikke i menyen: kanalen er privat, handlingen er bundet til en annen kanal, personen er en gjest og handlingen har ingen kanal, eller utgående webhooks er slått av.
• 404 ved kjøring av en meldingshandling: handlingen finnes ikke, eller den dekker ikke kanalen for den meldingen for den personen. 429: personen kjørte mer enn 10 handlinger på ett minutt. 502: ingen av callback-URL-ene kunne nås (loggen har årsaken).
• Logger: med Aktiver webhook-feilsøking på (LogSettings.EnableWebhookDebugging) og loggnivået på DEBUG, logger serveren lastene for mislykkede innkommende forespørsler. Mislykkede utgående kall logges som Outgoing Webhook POST failed.