Webhooks

En inkommande webhook gör att ett annat system kan posta i en kanal genom att skicka JSON till en hemlig URL. En utgående webhook gör det motsatta: den skickar meddelanden till din URL, de som börjar med ett trigger-ord eller de som personer väljer i meddelandemenyn, och postar det du svarar med.

Var du hanterar webhooks

Öppna din avatar i övre högra hörnet och välj sedan Integrationer. Integrationsssiderna för den aktuella communityn listar Inkommande webhook och Utgående webhook. Varje webhook tillhör en community.

Som standard kan communityadministratörer och systemadministratörer skapa webhooks. En systemadministratör kan ge rättigheter till andra roller i behörighetsinställningarna i Systemkonsolen. En systemadministratör kan också stänga av varje typ i Systemkonsol › Integrationer › Hantera integrationer: Aktivera inkommande Webhooks och Aktivera utgående Webhooks är båda aktiverade som standard.

Skapa en inkommande webhook

1. I Integrationer, välj Inkommande webhook och sedan Aktivera Utgående Webhooks.
2. Fyll i en Titel och en Beskrivning: de visas endast på integrationsssiderna.
3. Välj den Kanal som meddelandena går till som standard. För en privat kanal måste du vara medlem i den.
4. Markera Lås till denna kanal om avsändare inte ska kunna posta någon annanstans.
5. Välj eventuellt ett Användarnamn och en Profilbild-URL för dess meddelanden (se Namn och ikon).
6. Välj Spara. Kopiera den visade 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 är nyckeln. Från kommandoraden: amctl webhook create-incoming --channel <channel id> --user <user> --display-name "CI".

Skicka ett meddelande till en inkommande 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:"}'

Servern svarar med 200 och kroppen ok. Den accepterar också application/x-www-form-urlencoded med JSON i ett payload-fält, precis som Slacks webhooks, så verktyg gjorda för Slack fungerar oftast utan ändringar.

Varje meddelande som en webhook postar har en BOT-tagg bredvid sitt namn, även när det visas under skaparens namn, så att personer kan skilja det från ett meddelande från en riktig person. Webhookmeddelanden aktiverar aldrig utgående webhooks.

Namn och ikon

En webhook postar som den person som skapade den, om inte servern tillåter åsidosättningar. Två inställningar i Systemkonsol › Integrationer › Hantera integrationer, båda inaktiverade som standard, ändrar detta:

• Aktivera att integrationer kan skriva över användarnamn (ServiceSettings.EnablePostUsernameOverride): webhooks Användarnamn eller begäran username visas istället; utan någon av dem är namnet webhook.
• Aktivera att integrationer kan skriva över profilbilder (ServiceSettings.EnablePostIconOverride): webhooks Profilbild, eller begäran icon_url eller icon_emoji, visas.

Ett värde i begreandet har företräde framför det som är sparat på webhooken.

Bilagor

Bilagor lägger till strukturerat innehåll under texten. De följer Slacks meddelandebilagsformat:

{
  "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: steg och diagram

Antimatter lägger till två fält i bilagor som visas av standardgränssnittet:

• stages: ett pipelines steg som piller, upp till 20. Varje steg är {"name", "status"}, där status är passed, failed, running, pending, skipped eller canceled.
• chart: en liten linjediagram över senare värden, {"values": [2 to 200 numbers], "threshold": number, "label": "…"}. Tröskelvärdet ritas som en streckad linje, för en aviseringars gräns.

{
  "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 klassiska gränssnittet och andra klienter ignorerar dessa två fält, så lägg in det viktiga i text eller fields också.

Skapa en utgående webhook

En utgående webhook övervakar communityns publik kanaler. Den skickar ett meddelande till din URL antingen när meddelandets första ord matchar ett av dess trigger-ord, eller när någon väljer det i meddelandets meny (en meddelandehandling).

1. I Integrationer, välj Utgående webhook och sedan Aktivera Utgående Webhooks.
2. Fyll i Titel och Beskrivning.
3. Välj Innehållstyp för begäran: application/x-www-form-urlencoded eller application/json.
4. Välj en Kanal, ange Aktiveringsorden (en per varje rad), eller båda. Med en kanal och inga aktiveringsord skickas alla meddelanden i den kanalen. Med båda måste meddelandet matcha båda.
5. Under Aktiveras när, välj Första ordet matchar ett trigger-ord exakt, Första ordet startar med ett trigger-ord eller Från meddelandemenyn. Med Från meddelandemenyn försvinner trigger-orden, Kanal är valfri (utan en, erbjuds handlingen i varje publik kanal i communityn) och Titel är obligatorisk: det är handlingens namn i menyn.
6. Ange Återanrops-URLer (en per rad). Varje URL får varje matchande meddelande.
7. Välj eventuellt Användarnamn och Profilbild som används för svar. För en handling från meddelandemenyn ersätter fältet Icon Profilbild: URL:en till en .png- eller .jpg-bild eller, i Antimatters standardgränssnitt, en uppladdad bild. Menyn visar den i grått; utan en får handlingen en neutral ikon.
8. Välj Spara och kopiera den visade token. Din tjänst använder den för att kontrollera att begäranden kommer från din server.

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 för exakt matchning, 1 för "börjar med", 2 för "från meddelandemenyn"). En webhook med trigger_when 2 tar inga utlösande ord och kräver ett display_name. Ladda upp dess ikon med POST /api/v4/hooks/outgoing/{hook_id}/icon (multipart, fält image: PNG, JPEG eller GIF, lagras som en 128 px PNG); dess icon_url pekar sedan på GET /api/v4/hooks/outgoing/{hook_id}/icon.

Den utgående begäran

Antimatter skickar en POST med dessa fält, som JSON eller formulär-kodad beroende på innehållstypen:

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

Jämför token med webhooks token innan du gör något. I den formulärkoderade versionen är timestamp i sekunder istället för millisekunder. Servern väntar på ditt svar så länge som Timeout vid integrationer tillåter (30 sekunder som standard, ServiceSettings.OutgoingIntegrationRequestsTimeout).

Svara på en utgående webhook

För att posta ett svar, svara med JSON. För att inte posta något, svara 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 och attachments: svaret. Utan någon av dem, ingenting postas.
• response_type: comment postar svaret i tråden för det utlösande meddelandet; annars går det till kanalen.
• username, icon_url: visas när servern tillåter åsidosättningar; annars används webhookens egna värden.
• props, type, priority: som för inkommande webhooks.

Svaret postas som webhookens skapare, under det åsidosatta namnet när det finns. För allt längre än ett kort svar, svara omedelbart och posta senare med en inkommande webhook eller API:et.

Meddelandeåtgärder

En åtgärd för meddelanden är en utgående webhook med Aktiveras när satt till Från meddelandemenyn. Den utlöses aldrig för publicerade meddelanden. Istället ser den i ett meddelandes meny: Åtgärder för meddelanden (⋯) › Fler åtgärder, under rubriken Integrationer, med dess ikon. Den klassiska gränssnittet visar inte åtgärder för meddelanden. När den väljs skickas det enskilda meddelandet till callback-URL:erna, och en kort avisering visar Skickat till åtgärdens namn, eller visar din ephemeral_text.

• Var den visas: i webhooks kanalen eller, utan en kanal, i alla publika kanaler i dess arbetsyta. Endast publika kanaler har åtgärder för meddelanden.
• Gäster får endast åtgärderna som är bundna till en kanal de är i, inte de som gäller för hela arbetsytan.
• Arkiverade och skrivskyddade kanaler: meddelandet kan fortfarande skickas. När en kanal arkiveras raderas webhooks som är bundna till den, så en arkiverad kanal behåller endast de åtgärder som gäller för hela arbetsytan. Ett svar som personen inte kunde publicera där visas endast för dem.
• Gräns för antal anrop: varje person kan köra 10 åtgärder för meddelanden per minut, efter en burst på 5. Över det svarar servern med 429.
• Privata nätverk: som för andra utgående webhooks, måste interna adresser tillåtas i Tillåt osäkra interna anslutningar till.

Begäran

Betalningen skickas som JSON eller formulärkodat, enligt webhooks innehållstyp:

{
  "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 och user_name är personen som valde åtgärden; post_user_id och post_user_name är meddelandets författare.
• Endast det meddelandet skickas, aldrig resten av dess tråd.
• files listar meddelandets filer endast om personen som valde åtgärden kan ladda ner dem. Att ladda ner en link kräver en session eller en token, som för alla filer i API:et.
• Ett meddelande som bränns vid läsning skickas utan text eller filer, med burn_on_read satt till true.
• Vid formulärkodning kommer filerna som upprepade fält file_id, file_name och file_link, i samma ordning.

Svaret

Svara som för vilken utgående webhook som helst (se Svara på en utgående webhook): text eller attachments publicerar ett svar i kanalen, och "response_type": "comment" publicerar det i meddelandets tråd. Du kan också svara med ephemeral_text (avkortas till 300 tecken): det visas endast för den person som valde åtgärden, i aviseringen. En tom kropp publicerar ingenting.

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

Med API:et

• GET /api/v4/channels/{channel_id}/message_actions: de åtgärder du kan välja i en kanal, med id, display_name, description och icon_url. Våder och callback-URL:er returneras inte.
• POST /api/v4/posts/{post_id}/message_actions/{hook_id}: kör en åtgärd på ett meddelande du kan läsa. Den svarar med {"ephemeral_text"}.

När en webhook inte fungerar

• 501 från hook-URL:en: inkommande webhooks är avstängda på servern.
• 400 "Failed to decode the payload…": JSON:en är ogiltig, eller så heter formulärfältet inte payload. "No text specified." betyder att begäran varken har text eller attachments.
• 403: webhooks är låst till en annan kanal, eller så kan dess ägare inte längre läsa kanalen.
• En utgående webhook aktiveras aldrig: kanalen är privat, utlösaren är inte det första ordet, meddelandet kom från en webhook, eller webhooken är inställd på att aktiveras Från meddelandemenyn.
• En meddelandeåtgärd saknas i menyn: kanalen är privat, åtgärden är kopplad till en annan kanal, personen är en gäst och åtgärden har ingen kanal, eller så är utgående webhooks avstängda.
• 404 vid körning av en meddelandeåtgärd: åtgärden finns inte, eller så omfattar den inte meddelandets kanal för den personen. 429: personen körde mer än 10 åtgärder på en minut. 502: ingen av callback-URL:erna kunde nås (loggen innehåller orsaken).
• Loggar: med Aktiverar Webhook-debugg på (LogSettings.EnableWebhookDebugging) och loggnivån på DEBUG loggar servern lasten för misslyckade inkommande förfrågningar. Misslyckade utgående anrop loggas som Outgoing Webhook POST failed.