App webhooks

Ang app webhook ay isang per-channel URL na puwedeng pag-POST-an ng CI runner, monitoring tool, o external service mo para maglagay ng message sa isang GameVox channel. Walang gateway session na kailangan. Nagpo-post ang messages bilang bot user mo, gamit ang avatar at username ng bot.

Mga limit

50 webhooks kada application.
Pangalan: 1–80 characters.
Content: 1–4000 characters kada message.
Isang webhook = isang channel. Kailangan ng manage_server permission sa server ng channel para makagawa ng webhook.

Token format

WH.{8-char na prefix}.{base64 random}

halimbawa: WH.aB7xZ2k1.q9F7v1NkN3J2Wm8L6PpV5cU0Yr1zQbXa

Ipinapakita ang buong token nang isang beses lang, pag-create. Bcrypt hash lang kasama ang prefix at huling 4 characters ang sine-save namin para sa display. Kung nawala mo ang token, i-delete ang webhook at gumawa ng bago.

Paggawa ng webhook (portal)

Buksan ang application mo → Mga Webhook tab → Bagong Webhook. Pumili ng server na kaya mong i-manage, pumili ng channel, at bigyan ito ng pangalan. Ipinapakita ng reveal modal ang buong token at ang ready-to-paste na execute URL. Kopyahin ito bago isara; hindi na ito ipapakita ulit ng portal.

Endpoints

Dalawang auth mode: bot token para sa management, URL token para sa execute.

Bot-token auth (management)

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}

URL-token auth (execute + edit)

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}

Walang Authorization header para sa URL-token routes. Ang token sa URL path mismo ang auth. Ituring na secret ang URL.

Execute request

JSON body:

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

{
  "content": "Pumasa ang Build #4811 sa production.",
  "embeds": [
    {
      "title": "Green ang CI",
      "url": "https://ci.example.com/builds/4811",
      "description": "42 tests, 0 failures.",
      "color": 3066993
    }
  ]
}

multipart/form-data body (para sa attachments):

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

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

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

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

Response (parehong content types):

{
  "id": "1199283740192847400",
  "channel_id": "1199283740192847000",
  "content": "Pumasa ang Build #4811 sa production.",
  "embeds": [ ... ],
  "attachments": [ ... ],
  "timestamp": "2026-05-21T15:42:09Z"
}

Ano ang supported

Content: plain text, 1–4000 characters.
Embeds: buong Discord embed shape (title, description, url, color, timestamp, footer, image, thumbnail, author, fields). Puwede ang maraming embeds kada message.
Attachments: mag-upload ng files gamit ang multipart/form-data na may payload_json part; may kasamang CDN URLs ang response.
Reply targeting: ipasa ang message_reference sa payload_json.
?wait=true: implicit; laging ang resolved message ang response.
Edit / delete: mini-mirror ng PATCH / DELETE sa /webhooks/{id}/{token}/messages/{message.id} ang Discord.
Username / avatar overrides: hindi supported. Laging nagpo-post ang messages bilang bot user ng application.

Mga error

401: walang token, malformed, o hindi tugma.
404: na-delete ang webhook, o hindi existing ang id.
400: empty ang content at walang embeds/attachments, o lampas sa 4000 characters ang content.
405: hindi supported ang verb sa route na ito.
413: lampas ang attachment sa per-file size limit.

Pag-rotate

Walang rotate-in-place endpoint sa v1. I-delete ang webhook at gumawa ng bago. Agad na titigil gumana ang lumang token pag-delete (hindi isinasama ng execute path ang soft-deleted rows).

Mga pagkakaiba sa Discord

Ang webhooks ay pag-aari ng application, hindi ng isang server admin. Hindi nade-delete ang webhook row kapag na-delete ang channel; magbabalik ng 404 ang susunod na execute mula sa channel join sa lookup.
Walang username / avatar_url overrides kada request. Nakapirmi sa bot user ang identity.
Hindi ine-enforce ang per-channel webhook cap; per-application ang cap (50).
Vine-verify ang auth gamit ang bcrypt, kaya sinadyang mabagal ang token compare. Huwag i-spam ang endpoint sa mahihigpit na loops.
Self-hosted servers: hindi naka-route ang webhooks sa self-hosted boxes. Nagbabalik ng 404 ang lahat ng webhook endpoints para sa self-hosted guild targets. Tingnan ang Self-hosted docs.

← Bumalik sa docs