Webhooks

En indgående webhook giver et andet system mulighed for at poste i en kanal ved at sende JSON til en hemmelig URL. En udgående webhook gør det modsatte: den sender beskeder til din URL, enten dem der starter med et triggerord, eller dem som folk vælger i beskedmenuen, og poster det, du svarer med.

Hvor du administrerer webhooks

Åbn fællesskabsmenuen, vælg Teamindstillinger, og klik på Integrationer i slutningen af fanerne. Integrationsiderne for det aktuelle fællesskab viser Indgående webhooks og Udgående webhooks. Hver webhook tilhører ét fællesskab.

Som standard kan fællesskabsadministratorer og systemadministratorer oprette webhooks. En systemadministrator kan give andre roller denne rettighed i rettighedsindstillingerne i Systemkonsol. En systemadministrator kan også slå hver type fra i Systemkonsol › Integrationer › Integrationshåndtering: Aktivér indgående Webhooks og Aktivér udgående webhooks er begge aktiveret som standard.

Opret en indgående webhook

1. Vælg Indgående webhooks i Integrationer, og vælg derefter Tilføj indgående webhook.
2. Udfyld en Titel og en Beskrivelse: De vises kun på integrations siderne.
3. Vælg den Kanal, beskederne sendes til som standard. For en privat kanal skal du være medlem af den.
4. Marker Lås til denne kanal, hvis afsendere ikke skal kunne poste andre steder.
5. Vælg evt. et Brugernavn og en Profilbillede-URL til dets beskeder (se Navn og ikon).
6. Vælg Gem. Kopiér den viste URL: 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øglen. Fra kommandolinjen: amctl webhook create-incoming --channel <channel id> --user <user> --display-name "CI".

Send en besked til en indgående 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 accepterer også application/x-www-form-urlencoded med JSON i et payload-felt, ligesom Slacks webhooks, så værktøjer lavet til Slack normalt virker uden ændringer.

Hver besked, en webhook poster, bærer et BOT-mærke ved siden af navnet, selv når den vises under opretters navn, så folk kan skelne den fra en besked fra en rigtig person. Webhook-beskeder udløser aldrig udgående webhooks.

Navn og ikon

En webhook poster som den person, der oprettede den, medmindre serveren tillader overskrivninger. To indstillinger i Systemkonsol › Integrationer › Integrationshåndtering, begge slået fra som standard, ændrer dette:

• Aktivér integrationer, der kan overskrive brugernavne (ServiceSettings.EnablePostUsernameOverride): webhooken Brugernavn eller anmodningens username vises i stedet; hvis ingen af dem er angivet, er navnet webhook.
• Aktivér, at integrations kan overskrive profilbilleder (ServiceSettings.EnablePostIconOverride): Webhook'ets Profilbillede, eller anmodningens icon_url eller icon_emoji, vises.

En værdi i anmodningen har forrang over den gemte på webhook'et.

Vedhæftninger

Vedhæftninger tilføjer struktureret indhold under teksten. De følger Slacks format for beskedvedhæftninger:

{
  "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: faser og diagrammer

Antimatter tilføjer to felter til vedhæftninger, som vises af standardgrænsefladen:

• stages: Trin i en pipeline som piller, op til 20. Hvert trin er {"name", "status"}, hvor status kan være passed, failed, running, pending, skipped eller canceled.
• chart: et lille linjediagram over seneste værdier, {"values": [2 to 200 numbers], "threshold": number, "label": "…"}. Tærsklen tegnes som en streglinje, for en alarms grænse.

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

Den klassiske grænseflade og andre klienter ignorerer disse to felter, så sørg for også at inkludere de vigtigste oplysninger i text eller fields.

Opret en udgående webhook

En udgående webhook overvåger fællesskabets offentlige kanaler. Den sender en besked til din URL, enten når beskedens første ord matcher ét af dens triggerord, eller når nogen vælger den i beskedens menu (en beskedhandling).

1. Vælg Udgående webhooks i Integrationer, og vælg derefter Tilføj udgående webhook.
2. Udfyld Titel og Beskrivelse.
3. Vælg Indholdstype for anmodningen: application/x-www-form-urlencoded eller application/json.
4. Vælg en Kanal, indtast Udløsende ord (ét pr. linje), eller begge dele. Med en kanal og ingen udløsende ord sendes alle beskeder i den kanal. Med begge dele skal beskeden matche begge.
5. Under Udløses ved vælger du Første ord matcher et triggerord præcist, Første ord starter med et triggerord eller Fra beskedmenuen. Med Fra beskedmenuen forsvinder triggerordene, Kanal er valgfri (uden en kan handlingen tilbydes i alle offentlige kanaler i fællesskabet), og Titel er obligatorisk: det er handlingens navn i menuen.
6. Indtast Callback-URL’er (én pr. linje). Hver URL modtager alle matchende beskeder.
7. Vælg evt. Brugernavn og Profilbillede, der bruges til svar. For en handling fra beskedmenuen erstatter Ikone-feltet Profilbillede: URL'en til et .png- eller .jpg-billede eller, i Antimatters standardgrænseflade, et uploadet billede. Menuen viser det i grå; uden et får handlingen et neutralt ikon.
8. Vælg Gem og kopier den viste token. Din service bruger den til at verificere, at anmodninger kommer fra din server.

Med API: POST /api/v4/hooks/outgoing med {"team_id", "channel_id", "trigger_words", "trigger_when", "callback_urls", "content_type", "display_name"} (trigger_when: 0 for en eksakt match, 1 for "starter med", 2 for "fra beskedmenuen"). En webhook med trigger_when 2 tager ingen udløsende ord og kræver et display_name. Upload dens ikon med POST /api/v4/hooks/outgoing/{hook_id}/icon (multipart, felt image: PNG, JPEG eller GIF, gemt som en 128 px PNG); dens icon_url peger derefter på GET /api/v4/hooks/outgoing/{hook_id}/icon.

Den udgående anmodning

Antimatter sender en POST med disse felter, som JSON eller formular-kodet afhængigt af indholdstypen:

{
  "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 webhook'ets token, før du gør noget. I den formkodede version er timestamp i sekunder i stedet for millisekunder. Serveren venter på dit svar i den tid, som Integration anmodning timeout tillader (30 sekunder som standard, ServiceSettings.OutgoingIntegrationRequestsTimeout).

Svar på en outgoing webhook

For at sende et svar, svar med JSON. For ikke at sende noget, svar med et tomt 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. Uden begge dele, sendes der intet.
• response_type: comment sender svaret i tråden for den udløsende besked; ellers sendes det til kanalen.
• username, icon_url: vises, når serveren tillader overrides; webhook'ens egne værdier bruges ellers.
• props, type, priority: som for incoming webhooks.

Svaret sendes som webhook'ens opretter, under det overstyrede navn, hvis der er ét. For alt længere end et hurtigt svar, svar straks og send senere med en incoming webhook eller API'et.

Beskedhandlinger

En beskedhandling er en udgående webhook med Udløses ved sat til Fra beskedmenuen. Den udløses aldrig på postede beskeder. I stedet ser folk den i en beskedmenu: Beskedhandlinger (⋯) › Flere handlinger, under overskriften Integrationer, med dens ikon. Det klassiske grænseflade viser ikke beskedhandlinger. Når den vælges, sendes den pågældende besked til callback-URL'erne, og en kort notifikation viser Sendt til handlingens navn, eller viser din ephemeral_text.

• Hvor den vises: i webhook'ens kanal, eller, uden en kanal, i alle offentlige kanaler i dens fællesskab. Kun offentlige kanaler har beskedhandlinger.
• Gæster får kun de handlinger, der er bundet til en kanal, de er i, ikke de fællesskabsomfattende.
• Arkiverede og skrivebeskyttede kanaler: beskeden kan stadig sendes. Når en kanal arkiveres, slettes de webhooks, der er bundet til den, så en arkiveret kanal beholder kun de fællesskabsomfattende handlinger. Et svar, som personen ikke kunne poste der, vises kun for vedkommende.
• Hastighedsbegrænsning: hver person kan køre 10 beskedhandlinger pr. minut, efter en burst på 5. Over dette svarer serveren med 429.
• Private netværk: som for andre udgående webhooks, skal interne adresser tillades i Tillad upålidelige interne forbindelser til.

Anmodningen

Betalelasten sendes som JSON eller formular-koderet, som webhook'ens indholdstype angiver:

{
  "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 den person, der valgte handlingen; post_user_id og post_user_name er beskedens forfatter.
• Kun den pågældende besked sendes, aldrig resten af dens tråd.
• files viser beskedens filer kun, hvis den person, der valgte handlingen, kan downloade dem. Download af en link kræver en session eller en token, som for enhver fil i API'et.
• En besked, der brændes ved læsning, sendes uden tekst og filer, med burn_on_read sat til true.
• Ved form-encoding kommer filerne som gentagne file_id, file_name og file_link-felter i samme rækkefølge.

Svaret

Svar som for enhver udgående webhook (se Svar på en udgående webhook): text eller attachments poster et svar i kanalen, og "response_type": "comment" poster det i beskeden's tråd. Du kan også svare med ephemeral_text (afkortet til 300 tegn): det vises kun for den person, der valgte handlingen, i notifikationen. Et tomt svarposter ingenting.

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

Med API'et

• GET /api/v4/channels/{channel_id}/message_actions: de handlinger, du kan vælge i en kanal, med id, display_name, description og icon_url. Hverken tokens eller callback-URL'er returneres.
• POST /api/v4/posts/{post_id}/message_actions/{hook_id}: udfører en handling på en besked, du kan læse. Den svarer med {"ephemeral_text"}.

Når en webhook ikke virker

• 501 fra hook URL: incoming webhooks er slået fra på serveren.
• 400 "Failed to decode the payload…": JSON er ugyldig, eller form-feltet hedder ikke payload. "No text specified." betyder, at anmodningen hverken har text eller attachments.
• 403: webhook'ens er låst til en anden kanal, eller dens ejer kan ikke længere læse kanalen.
• En udgående webhook udløses aldrig: kanalen er privat, udløseren er ikke det første ord, beskeden kom fra en webhook, eller webhook'en er indstillet til at udløses Fra beskedmenuen.
• En beskedhandling er ikke i menuen: kanalen er privat, handlingen er bundet til en anden kanal, personen er en gæst, og handlingen har ingen kanal, eller udgående webhooks er slået fra.
• 404 ved udførelse af en beskedhandling: handlingen findes ikke, eller den dækker ikke beskeden's kanal for den pågældende person. 429: personen udførte mere end 10 handlinger på et minut. 502: ingen af callback-URL'erne kunne nås (loggen indeholder årsagen).
• Et opslag i et forum afvises: Hookens besked skal have en titel (props.am_thread_title); fejlen angiver årsagen, f.eks. app.post.forum.title_required.app_error, i stedet for en generel fejlbesked (se Channel types).
• Logs: med Aktivér webhook-fejlafsløring slået til (LogSettings.EnableWebhookDebugging) og logniveauet sat til DEBUG, logger serveren payloads for mislykkede indgående anmodninger. Mislykkede udgående opkald logges som Outgoing Webhook POST failed.