App webhooks

An app webhook is a per-channel URL your CI runner, monitoring tool, or external service can POST to in order to drop a message into a GameVox channel — no gateway session required. Messages post as your bot user, with the bot's avatar and username.

Limits

50 webhooks per application.
Name: 1–80 characters.
Content: 1–4000 characters per message.
One webhook = one channel. Creating a webhook requires the manage_server permission in the channel's server.

Token format

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

example: WH.aB7xZ2k1.q9F7v1NkN3J2Wm8L6PpV5cU0Yr1zQbXa

The full token is shown exactly once, at create time. We store only the bcrypt hash plus the prefix and last 4 characters for display. If you lose a token, delete the webhook and create a new one.

Creating a webhook (portal)

Open your application → Webhooks tab → New Webhook. Pick a server you can manage, pick a channel, give it a name. The reveal modal shows the full token and the ready-to-paste execute URL. Copy it before dismissing — the portal will never show it again.

Execute endpoint

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

{
  "content": "Build #4811 passed on production."
}

No Authorization header — the token in the URL path is the auth. Treat the URL like a secret.

Response:

{
  "id": "1199283740192847400",
  "channel_id": "1199283740192847000",
  "timestamp": "2026-05-21T15:42:09Z"
}

What's supported

Plain text content only in v1.
Embeds, files, and reply targeting are not yet wired (planned).
Username / avatar overrides are not supported — messages always post as the application's bot user.
?wait=true is implicit: the response is always the resolved message.

Errors

401 — token missing, malformed, or doesn't match.
404 — webhook deleted, or id doesn't exist.
400 — empty content, or longer than 4000 characters.
405 — anything other than POST.

Rotating

There is no rotate-in-place endpoint in v1. Delete the webhook and create a new one — the old token stops working immediately on delete (the execute path excludes soft-deleted rows).

Differences from Discord

Webhooks are owned by the application, not by a server admin. Deleting the channel does not delete the webhook row; the next execute returns 404 from the channel join in the lookup.
No username / avatar_url overrides per request — identity is fixed to the bot user.
Per-channel webhook cap is not enforced; the cap is per-application (50).
Auth is verified with bcrypt — token compare is intentionally slow. Don't hammer the endpoint in tight loops.

← Back to docs