Webhooki

Przychodzący webhook pozwala innemu systemowi publikować wiadomości w kanale, wysyłając JSON na tajny adres URL. Wychodzący webhook robi odwrotnie: wysyła do Twojego adresu URL wiadomości, które zaczynają się od słowa wyzwalającego, lub te, które użytkownicy wybiorą w menu wiadomości, a następnie publikuje to, co odpowiesz.

Gdzie zarządzać webhookami

Kliknij swój awatar w prawym górnym rogu, a następnie wybierz Integracje. Strony integracji bieżącej społeczności zawierają listę Przychodzące Webhooki i Wychodzące Webhooki. Każdy webhook należy do jednej społeczności.

Domyślnie administratorzy społeczności i administratorzy systemu mogą tworzyć webhooki. Administrator systemu może przyznać to prawo innym rolom w ustawieniach uprawnień w Konsola systemu › Integracje › Zarządzanie Integracjami: Włączy wychodzące webhooki i Włączyć wychodzące webhooki są domyślnie włączone.

Utwórz webhook przychodzący

1. W Integracje wybierz Przychodzące Webhooki, a następnie Dodaj przychodzący Webhook.
2. Wpisz Tytuł i Opis: są one widoczne tylko na stronach integracji.
3. Wybierz Kanał, do którego domyślnie trafiają wiadomości. W przypadku kanału prywatnego musisz być jego członkiem.
4. Zaznacz Zablokuj do tego kanału, jeśli nadawcy nie powinni mieć możliwości publikowania gdzie indziej.
5. Opcjonalnie ustaw Nazwa użytkownika i adres URL Zdjęcie Profilowe dla jego wiadomości (patrz Nazwa i ikona).
6. Wybierz Zapisz. Skopiuj wyświetlony adres URL: https://chat.example.com/hooks/<key>.

Z API: POST /api/v4/hooks/incoming z {"channel_id", "display_name", "description", "username", "icon_url", "channel_locked"}; id w odpowiedzi to klucz. Z wiersza poleceń: amctl webhook create-incoming --channel <channel id> --user <user> --display-name "CI".

Wyślij wiadomość do webhooka przychodzącego

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

Serwer odpowiada 200 z treścią ok. Akceptuje również application/x-www-form-urlencoded z JSON w polu payload, tak jak webhooki Slacka, więc narzędzia stworzone dla Slacka zwykle działają bez zmian.

Każda wiadomość opublikowana przez webhook ma obok nazwy tag BOT, nawet gdy jest wyświetlana pod nazwą jej twórcy, aby użytkownicy mogli ją odróżnić od wiadomości od prawdziwej osoby. Wiadomości webhooków nigdy nie wyzwalają wychodzących webhooków.

Nazwa i ikona

Webhook publikuje jako osoba, która go utworzyła, chyba że serwer pozwala na nadpisywanie. Dwa ustawienia w Konsola systemu › Integracje › Zarządzanie integracjami, domyślnie wyłączone, zmieniają to:

• Włącz możliwość nadpisywania nazw użytkowników przez integracje (ServiceSettings.EnablePostUsernameOverride): wyświetlana jest Nazwa użytkownika webhooka lub username z żądania; jeśli żadne z nich nie jest podane, nazwą jest webhook.
• Włącz integracje pozwalające na nadpisanie ikon zdjęć profilowych (ServiceSettings.EnablePostIconOverride): wyświetlane jest Zdjęcie Profilowe webhooka, lub icon_url lub icon_emoji z żądania.

Wartość z żądania ma pierwszeństwo przed tą zapisaną na webhooku.

Załączniki

Załączniki dodają ustrukturyzowaną treść pod tekstem. Podążają za formatem załączników wiadomości Slack:

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

Karty: etapy i wykresy

Antimatter dodaje do załączników dwa pola, które są wyświetlane przez domyślny interfejs:

• stages: kroki potoku jako etykiety (pills), do 20. Każdy ma postać {"name", "status"}, a status to passed, failed, running, pending, skipped lub canceled.
• chart: mały wykres liniowy ostatnich wartości, {"values": [2 to 200 numbers], "threshold": number, "label": "…"}. Próg jest rysowany jako linia przerywana, jako limit dla alertu.

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

Klasyczny interfejs i inne klienty ignorują te dwa pola, więc umieszczaj również kluczowe informacje w polach text lub fields.

Utwórz webhook wychodzący

An outgoing webhook watches the public channels of a community. It sends a message to your URL either when the message's first word matches one of its trigger words, or when someone picks it in the message's menu (a message action).

1. W sekcji Integracje wybierz Wychodzące Webhooki, a następnie Dodaj wychodzący Webhook.
2. Wpisz Tytuł i Opis.
3. Wybierz Typ zawartości żądania: application/x-www-form-urlencoded lub application/json.
4. Wybierz Kanał, wpisz Słowa wyzwalacze (jeden na linię) lub oba. Przy kanale bez słów wyzwalających wysyłane są wszystkie wiadomości z tego kanału. Przy obu, wiadomość musi spełniać oba warunki.
5. W sekcji Wyzwól gdy wybierz Pierwsze słowo dokładnie pasuje do słowa wyzwalającego, Pierwsze słowo zaczyna się słowem wyzwalającym lub Z menu wiadomości. Przy Z menu wiadomości słowa wyzwalające znikają, Kanał jest opcjonalny (bez niego działanie jest oferowane we wszystkich publicznych kanałach społeczności), a Tytuł jest wymagany: to nazwa działania w menu.
6. Wpisz Zwrotne adresy URL (jeden na linię). Każdy adres URL otrzymuje każdą pasującą wiadomość.
7. Opcjonalnie ustaw Nazwę użytkownika i Zdjęcie Profilowe używane dla odpowiedzi. Dla działania z menu wiadomości pole Ikona zastępuje Zdjęcie Profilowe: adres URL obrazu .png lub .jpg lub, w domyślnym interfejsie Antimatter, przesłany obraz. Menu wyświetla go na szaro; bez niego działanie otrzymuje neutralną ikonę.
8. Wybierz Zapisz i skopiuj wyświetlany token. Twoja usługa używa go, aby zweryfikować, że żądania pochodzą z Twojego serwera.

Z API: POST /api/v4/hooks/outgoing z {"team_id", "channel_id", "trigger_words", "trigger_when", "callback_urls", "content_type", "display_name"} (trigger_when: 0 dla dokładnego dopasowania, 1 dla "zaczyna się", 2 dla "z menu wiadomości"). Webhook z trigger_when 2 nie przyjmuje słów wyzwalających i wymaga display_name. Prześlij jego ikonę przez POST /api/v4/hooks/outgoing/{hook_id}/icon (multipart, pole image: PNG, JPEG lub GIF, przechowywane jako PNG 128 px); jego icon_url wskazuje wtedy na GET /api/v4/hooks/outgoing/{hook_id}/icon.

Żądanie wychodzące

Antimatter wysyła żądanie POST z następującymi polami, jako JSON lub w kodowaniu formularza, w zależności od typu zawartości:

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

Porównaj token z tokenem webhooka przed wykonaniem jakichkolwiek działań. W wersji form-encoded timestamp jest wyrażony w sekundach, a nie w milisekundach. Serwer czeka na odpowiedź tak długo, jak pozwala na to Limit czasu żądania integracji (domyślnie 30 sekund, ServiceSettings.OutgoingIntegrationRequestsTimeout).

Odpowiedź na webhook wychodzący

Aby wysłać odpowiedź, zwróć JSON. Aby nie wysłać niczego, zwróć pustą zawartość.

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

• text i attachments: odpowiedź. Jeśli nie ma żadnego z tych pól, nic nie zostanie wysłane.
• response_type: wartość comment publikuje odpowiedź w wątku wiadomości, która wywołała webhook; w pozostałych przypadkach odpowiedź trafia do kanału.
• username, icon_url: wyświetlane, gdy serwer pozwala na nadpisywanie; w przeciwnym razie używane są własne wartości webhooka.
• props, type, priority: jak dla webhooków przychodzących.

Odpowiedź jest publikowana jako użytkownik, który utworzył webhooka, pod nadpisaną nazwą, jeśli taka istnieje. W przypadku odpowiedzi dłuższych niż krótka informacja, odpowiedz od razu, a resztę opublikuj później za pomocą webhooka przychodzącego lub API.

Akcje na wiadomości

Wiadomość akcji to webhook wychodzący, dla którego Wyzwól gdy jest ustawione na From the message menu. Nigdy nie jest wyzwalana przez wysłane wiadomości. Zamiast tego użytkownicy widzą ją w menu wiadomości: Wiadomości akcji (⋯) › Więcej Akcji, w sekcji Integracje, wraz z jej ikoną. Klasyczny interfejs nie wyświetla wiadomości akcji. Wybór tej opcji przesyła daną wiadomość do adresów URL wywołań zwrotnych, a krótki komunikat informuje, że została Sent to (wysłana do) nazwy akcji, lub wyświetla ephemeral_text.

• Miejsce wyświetlania: w kanale webhooka lub, w przypadku braku kanału, we wszystkich kanałach publicznych danej społeczności. Tylko kanały publiczne mają wiadomości akcji.
• Goście mają dostęp tylko do akcji przypisanych do kanału, w którym się znajdują, a nie do akcji ogólnospołecznościowych.
• Kanały zarchiwizowane i tylko do odczytu: wiadomość może nadal zostać wysłana. Archiwizacja kanału usuwa webhooki przypisane do niego, więc zarchiwizowany kanał zachowuje tylko akcje ogólnospołecznościowe. Odpowiedź, której użytkownik nie mógłby tam wysłać, jest wyświetlana tylko jemu.
• Limity: każdy użytkownik może wykonać 10 wiadomości akcji na minutę, po początkowym limicie 5. Po przekroczeniu tego limitu serwer zwraca 429.
• Sieci prywatne: podobnie jak w przypadku innych webhooków wychodzących, adresy wewnętrzne muszą być dozwolone w ustawieniu Pozwól na niezaufane połączenia wewnętrzne do.

Żądanie

Dane są przesyłane jako JSON lub form-encoded, zgodnie z typem zawartości webhooka:

{
  "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 i user_name to dane osoby, która wybrała akcję; post_user_id i post_user_name to dane autora wiadomości.
• Przesyłana jest tylko ta wiadomość, nigdy reszta jej wątku.
• files zawiera listę plików z wiadomości tylko wtedy, gdy osoba, która wybrała akcję, może je pobrać. Pobieranie link wymaga sesji lub tokena, jak w przypadku dowolnego pliku w API.
• Wiadomość typu burn-on-read jest wysyłana bez tekstu i plików, z ustawionym burn_on_read na true.
• W formacie form-encoded pliki są przesyłane jako powtarzane pola file_id, file_name i file_link, w tej samej kolejności.

Odpowiedź

Odpowiedz tak, jak dla dowolnego webhooka wychodzącego (patrz Odpowiedź na webhook wychodzący): text lub attachments publikuje odpowiedź w kanale, a "response_type": "comment" publikuje ją w wątku wiadomości. Możesz też odpowiedzieć za pomocą ephemeral_text (przycinane do 300 znaków): jest wyświetlana tylko osobie, która wybrała akcję, w powiadomieniu. Pusta treść nie publikuje niczego.

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

Za pomocą API

• GET /api/v4/channels/{channel_id}/message_actions: akcje, które możesz wybrać w kanale, wraz z id, display_name, description i icon_url. Nie zwraca się ani tokenów, ani adresów URL wywołań zwrotnych.
• POST /api/v4/posts/{post_id}/message_actions/{hook_id}: uruchamia akcję na wiadomości, do której masz dostęp do odczytu. Odpowiada {"ephemeral_text"}.

Gdy webhook nie działa

• 501 z adresu URL webhooka: webhooks przychodzące są wyłączone na serwerze.
• 400 "Failed to decode the payload…": JSON jest nieprawidłowy, albo pole formularza nie ma nazwy payload. "No text specified." oznacza, że żądanie nie zawiera ani text, ani attachments.
• 403: webhook jest przypięty do innego kanału, albo jego właściciel nie może już czytać tego kanału.
• Webhook wychodzący nigdy się nie uruchamia: kanał jest prywatny, wyzwalacz nie jest pierwszym słowem, wiadomość pochodzi z webhooka lub webhook jest ustawiony tak, aby uruchamiać się Z menu wiadomości.
• Akcja na wiadomości nie znajduje się w menu: kanał jest prywatny, akcja jest przypisana do innego kanału, osoba jest gościem, a akcja nie ma przypisanego kanału, lub webhoki wychodzące są wyłączone.
• 404 przy uruchamianiu akcji na wiadomości: akcja nie istnieje lub nie obejmuje kanału tej wiadomości dla tej osoby. 429: osoba uruchomiła więcej niż 10 akcji w ciągu minuty. 502: nie można było połączyć się z żadnym z adresów URL wywołań zwrotnych (powód znajduje się w logu).
• Logi: przy włączonym Włącz Debugowanie Webhooka (LogSettings.EnableWebhookDebugging) i poziomie logowania ustawionym na DEBUG, serwer loguje obciążenia nieudanych żądań przychodzących. Nieudane wywołania wychodzące są logowane jako Outgoing Webhook POST failed.