Webhooki aplikacji

Webhook aplikacji to URL przypisany do kanału, na który twój runner CI, narzędzie monitorujące lub zewnętrzna usługa może wysłać POST, żeby umieścić wiadomość na kanale GameVox. Sesja gatewaya nie jest potrzebna. Wiadomości są publikowane jako użytkownik twojego bota, z jego awatarem i nazwą użytkownika.

Limity

50 webhooków na aplikację.
Nazwa: 1–80 znaków.
Treść: 1–4000 znaków na wiadomość.
Jeden webhook = jeden kanał. Utworzenie webhooka wymaga uprawnienia manage_server na serwerze, do którego należy kanał.

Format tokena

WH.{8-znakowy prefiks}.{losowe base64}

przykład: WH.aB7xZ2k1.q9F7v1NkN3J2Wm8L6PpV5cU0Yr1zQbXa

Pełny token jest pokazywany dokładnie raz, przy tworzeniu. Przechowujemy tylko hash bcrypt oraz prefiks i ostatnie 4 znaki do wyświetlania. Jeśli zgubisz token, usuń webhook i utwórz nowy.

Tworzenie webhooka (portal)

Otwórz swoją aplikację → zakładka Webhooki → Nowy webhook. Wybierz serwer, którym możesz zarządzać, wybierz kanał i nadaj nazwę. Okno z tokenem pokazuje pełny token i gotowy do wklejenia URL execute. Skopiuj go przed zamknięciem; portal nigdy więcej go nie pokaże.

Endpointy

Dwa tryby uwierzytelniania: token bota do zarządzania, token w URL do execute.

Uwierzytelnianie tokenem bota (zarządzanie)

GET    /channels/{channel.id}/webhooks
POST   /channels/{channel.id}/webhooks
GET    /guilds/{guild.id}/webhooks
GET    /webhooks/{webhook.id}
PATCH  /webhooks/{webhook.id}
DELETE /webhooks/{webhook.id}

Uwierzytelnianie tokenem w URL (execute + edycja)

POST   /webhooks/{webhook.id}/{token}
GET    /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}
DELETE /webhooks/{webhook.id}/{token}
PATCH  /webhooks/{webhook.id}/{token}/messages/{message.id}
DELETE /webhooks/{webhook.id}/{token}/messages/{message.id}

Trasy z tokenem w URL nie używają nagłówka Authorization. Token w ścieżce URL jest uwierzytelnieniem. Traktuj URL jak sekret.

Żądanie execute

Treść JSON:

POST https://api.gamevox.com/webhooks/{webhook.id}/{token}
Content-Type: application/json

{
  "content": "Build #4811 przeszedł na produkcji.",
  "embeds": [
    {
      "title": "CI na zielono",
      "url": "https://ci.example.com/builds/4811",
      "description": "42 testy, 0 błędów.",
      "color": 3066993
    }
  ]
}

Treść multipart/form-data (dla załączników):

Content-Type: multipart/form-data; boundary=xyz

--xyz
Content-Disposition: form-data; name="payload_json"

{ "content": "Zobacz zrzut ekranu", "embeds": [ ... ] }
--xyz
Content-Disposition: form-data; name="files[0]"; filename="crash.png"
Content-Type: image/png

...binary...
--xyz--

Odpowiedź (dla obu typów zawartości):

{
  "id": "1199283740192847400",
  "channel_id": "1199283740192847000",
  "content": "Build #4811 przeszedł na produkcji.",
  "embeds": [ ... ],
  "attachments": [ ... ],
  "timestamp": "2026-05-21T15:42:09Z"
}

Co jest obsługiwane

Treść: zwykły tekst, 1–4000 znaków.
Embedy: pełny kształt embedów Discorda (title, description, url, color, timestamp, footer, image, thumbnail, author, fields). Wiele embedów w jednej wiadomości jest dozwolone.
Załączniki: wgrywaj pliki przez multipart/form-data z częścią payload_json; odpowiedź zawiera URL-e CDN.
Odpowiedzi na wiadomości: przekaż message_reference w payload_json.
?wait=true: domyślnie; odpowiedź to zawsze gotowa wiadomość.
Edycja / usuwanie: PATCH / DELETE na /webhooks/{id}/{token}/messages/{message.id} działają jak na Discordzie.
Nadpisywanie nazwy użytkownika / awatara: nieobsługiwane. Wiadomości zawsze są publikowane jako użytkownik bota aplikacji.

Błędy

401: brak tokena, token nieprawidłowy lub niepasujący.
404: webhook usunięty lub id nie istnieje.
400: puste content bez embedów i załączników albo content dłuższe niż 4000 znaków.
405: metoda nieobsługiwana na tej trasie.
413: załącznik przekracza limit rozmiaru pliku.

Rotacja

W v1 nie ma endpointu rotacji w miejscu. Usuń webhook i utwórz nowy. Stary token przestaje działać natychmiast po usunięciu (ścieżka execute pomija miękko usunięte wiersze).

Różnice względem Discorda

Webhooki należą do aplikacji, a nie do administratora serwera. Usunięcie kanału nie usuwa wiersza webhooka; następne execute zwraca 404 z powodu złączenia z kanałem przy wyszukiwaniu.
Brak nadpisywania username / avatar_url w żądaniu. Tożsamość jest na stałe przypisana do użytkownika bota.
Limit webhooków na kanał nie jest egzekwowany; limit dotyczy aplikacji (50).
Uwierzytelnianie jest weryfikowane przez bcrypt, więc porównanie tokena jest celowo wolne. Nie zasypuj endpointu żądaniami w ciasnych pętlach.
Serwery hostowane samodzielnie: webhooki nie są routowane do serwerów hostowanych samodzielnie. Wszystkie endpointy webhooków zwracają 404 dla gildii hostowanych samodzielnie. Zobacz dokumentację serwerów hostowanych samodzielnie.

← Powrót do dokumentacji