REST API v1 · 開發者
Webhook:把 Discord 伺服器事件直接送到你的伺服器
不必再反覆輪詢 API,讓 BotGG 主動通知你:當 Discord 伺服器發生事情時,例如餘額變動、升級、購買或新的客服單,BotGG 會向你的 HTTPS 端點送出一個有簽章的 JSON POST 請求。
開發者文件
本頁目錄
設定端點
- 在控制台中開啟伺服器的 API 區塊,新增一個 Webhook 端點:填入
https://網址,並選擇想接收的事件。 - 複製簽章密鑰(
whsec_…),它只會顯示一次,請儲存在你的伺服器上,例如存成BOTGG_WEBHOOK_SECRET。 - 從控制台傳送一個測試事件,事件類型為
webhook.test。請確認你的端點會驗證簽章,並回應2xx。
- 每個伺服器的端點數量:Free 方案 1 個,Pro 方案 10 個。
- 網址必須是公開的 HTTPS,而且不能包含使用者名稱或密碼;私人與內部位址會被拒絕。
- 更換密鑰會立即生效,請在更換後馬上把新的密鑰部署到你的伺服器。
傳送內容的樣子
每次傳送都是一個 POST 請求,內容為 JSON { id, type, createdAt, guildId, data }(data 依事件類型而定,請見事件),並帶有以下標頭:
| 標頭 | 說明 |
|---|---|
BotGG-Webhook-Id | 事件 ID(`evt_…`),每次重試都相同,請儲存下來以便忽略重複事件。 |
BotGG-Webhook-Timestamp | 此次嘗試簽署時的 Unix 時間(秒)。 |
BotGG-Signature | 以你端點的簽署密鑰,對時間戳記與原始內容計算出的 HMAC-SHA256 簽章。 |
POST /botgg-webhook HTTP/1.1
Content-Type: application/json
User-Agent: BotGG-Webhooks/1.0 (+https://botgg.app/developers/)
BotGG-Webhook-Id: evt_3Kq9Zx2mV7pL4nR8tW1y
BotGG-Webhook-Timestamp: 1791374460
BotGG-Signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
{"id":"evt_3Kq9Zx2mV7pL4nR8tW1y","type":"levels.levelUp","createdAt":"2026-10-07T12:00:00.000Z","guildId":"123456789012345678","data":{"userId":"876543210987654321","level":5,"previousLevel":4,"source":"activity"}}- 請在 10 秒內回應任何
2xx狀態。其他情況,包括錯誤狀態、逾時或重新導向(BotGG 不會跟隨重新導向),都會視為失敗的嘗試。 - 傳送失敗時,會在 1 分鐘、5 分鐘、30 分鐘、2 小時、6 小時和 24 小時後重試,總共最多 7 次嘗試,並使用相同的事件
id。 - 同一則事件可能會重複送達,也可能不依順序到達:請依
id去除重複,並用createdAt判斷順序。 - 持續失敗很長時間(一天以上)的端點會自動停用。修正問題後,請在控制台重新啟用,也可以在那裡重送失敗的事件。
驗證簽章
在信任請求之前,一定要確認它真的來自 BotGG。簽章是以你端點的密鑰,對時間戳記標頭、一個句點和原始請求內容計算出的十六進位 HMAC-SHA256:BotGG-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<body>")>。
- 讀取完全未經處理、與收到時一模一樣的原始內容(在任何 JSON 解析之前)。
- 如果
BotGG-Webhook-Timestamp與你的系統時間相差超過 5 分鐘,就拒絕該請求,這樣可以防止重放攻擊。 - 用你的密鑰計算
<timestamp>.<原始內容>的 HMAC,並以固定時間比較的方式,與BotGG-Signature中的每個v1=值比對。
// Node.js 18+ with Express. Verify against the RAW body — not a re-serialized JSON object.
import crypto from 'node:crypto';
import express from 'express';
const SECRET = process.env.BOTGG_WEBHOOK_SECRET; // whsec_… (shown once in the console)
const TOLERANCE_SECONDS = 300;
function verify(rawBody, timestamp, signatureHeader) {
const ts = Number(timestamp);
if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > TOLERANCE_SECONDS) return false;
const expected = crypto.createHmac('sha256', SECRET).update(`${ts}.${rawBody}`).digest('hex');
return String(signatureHeader ?? '')
.split(/[\s,]+/)
.some((part) => {
const m = /^v1=([0-9a-f]{64})$/.exec(part);
return Boolean(m) && crypto.timingSafeEqual(Buffer.from(m[1]), Buffer.from(expected));
});
}
const app = express();
app.post('/botgg-webhook', express.raw({ type: 'application/json' }), (req, res) => {
const raw = req.body.toString('utf8');
if (!verify(raw, req.get('BotGG-Webhook-Timestamp'), req.get('BotGG-Signature'))) return res.status(400).end();
const event = JSON.parse(raw);
res.status(204).end(); // acknowledge within 10 s, then do the work
// event.id is the same on every retry: skip events you have already handled
console.log(event.type, event.data);
});
app.listen(3000);# Python 3 with Flask. Verify against the RAW body bytes.
import hashlib, hmac, json, os, time
from flask import Flask, abort, request
SECRET = os.environ["BOTGG_WEBHOOK_SECRET"].encode() # whsec_… (shown once in the console)
TOLERANCE_SECONDS = 300
def verify(raw: bytes, timestamp, header) -> bool:
try:
ts = int(timestamp)
except (TypeError, ValueError):
return False
if abs(time.time() - ts) > TOLERANCE_SECONDS:
return False
expected = hmac.new(SECRET, f"{ts}.".encode() + raw, hashlib.sha256).hexdigest()
for part in (header or "").replace(",", " ").split():
if part.startswith("v1=") and hmac.compare_digest(part[3:], expected):
return True
return False
app = Flask(__name__)
@app.post("/botgg-webhook")
def botgg_webhook():
raw = request.get_data() # the exact bytes BotGG signed
if not verify(raw, request.headers.get("BotGG-Webhook-Timestamp"), request.headers.get("BotGG-Signature")):
abort(400)
event = json.loads(raw)
# event["id"] is the same on every retry: skip events you have already handled
print(event["type"], event["data"])
return "", 204事件
請讓每個端點只訂閱它需要的事件。內容結構在 v1 中保持穩定:欄位可能會新增,但不會被移除或更改型別,請忽略你不認識的欄位。Discord ID 是字串;BotGG 的紀錄 ID(交易、購買、客服單等)則是整數。
| 事件 | 功能 | 說明 |
|---|---|---|
bank.transaction | 銀行 | 銀行交易 — 任何餘額變動:每日獎勵、轉帳、商店扣款、管理員與 API 的變更。 |
levels.levelUp | 等級 | 升級 — 成員升到更高的等級(因活躍或管理員變更)。 |
shop.purchase | 商店 | 購買 — 成員購買了商店商品。 |
shop.refund | 商店 | 退款 — 一筆商店購買已退款。 |
tickets.opened | 客服單 | 客服單已開啟 — 建立了客服單頻道或討論串。 |
tickets.closed | 客服單 | 客服單已關閉 — 客服單已關閉(手動、自動或因開單者離開)。 |
members.joined | 成員 | 成員加入 — 有人加入了伺服器。 |
members.left | 成員 | 成員離開 — 有人離開了伺服器(或被踢出/停權)。 |
giveaways.ended | 抽獎 | 抽獎已結束 — 抽獎結束並已抽出得獎者。 |
moderation.caseCreated | 管理 | 管理案件 — 記錄了一筆新的管理案件(警告、禁言、踢出、停權……)。 |
applications.submitted | 申請 | 已提交申請 — 成員提交了申請表單(含回答)。 |
appeals.submitted | 停權申訴 | 已提交停權申訴 — 被停權的使用者提出了停權申訴(含回答)。 |
bank.transaction 銀行交易
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
transactionId | integer | 是 | 至少 0 |
userId | string | 是 | Discord snowflake id Discord ID(字串) |
type | string | 是 | Ledger type: daily, transfer_in, transfer_out, fee, admin_add, admin_remove, admin_set, flow, api, … |
amount | integer | 是 | Signed change (negative = debit) |
balanceAfter | integer | 是 | |
reason | string | null | 是 | |
counterpartyId | string | null | 是 | Discord snowflake id Discord ID(字串) |
actorId | string | null | 是 | Discord snowflake id Discord ID(字串) |
createdAt | string | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
{
"id": "evt_3Kq9Zx2mV7pL4nR8tW1y",
"type": "bank.transaction",
"createdAt": "2026-10-07T12:00:00.000Z",
"guildId": "123456789012345678",
"data": {
"transactionId": 98765,
"userId": "876543210987654321",
"type": "example",
"amount": 100,
"balanceAfter": 1350,
"reason": "Tournament prize",
"counterpartyId": "234567890123456789",
"actorId": "234567890123456789",
"createdAt": "2026-10-07T12:00:00.000Z"
}
}levels.levelUp 升級
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
userId | string | 是 | Discord snowflake id Discord ID(字串) |
level | integer | 是 | 至少 0 |
previousLevel | integer | 是 | 至少 0 |
source | string | 是 | 其中之一 activity, admin |
{
"id": "evt_3Kq9Zx2mV7pL4nR8tW1y",
"type": "levels.levelUp",
"createdAt": "2026-10-07T12:00:00.000Z",
"guildId": "123456789012345678",
"data": {
"userId": "876543210987654321",
"level": 5,
"previousLevel": 4,
"source": "activity"
}
}shop.purchase 購買
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
purchaseId | integer | 是 | 至少 0 |
userId | string | 是 | Discord snowflake id Discord ID(字串) |
item | object | 是 | |
item.id | integer | null | 是 | null when the item was deleted since 至少 0 |
item.name | string | 是 | |
item.emoji | string | null | 是 | |
item.type | string | 是 | role | color | item | … |
store | object | 是 | id/name null = the built-in Main store |
store.id | integer | null | 是 | 至少 0 |
store.name | string | null | 是 | |
price | integer | 是 | 至少 0 |
status | string | 是 | owned | used | refunded |
roleId | string | null | 是 | Discord snowflake id Discord ID(字串) |
expiresAt | string | null | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
createdAt | string | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
{
"id": "evt_3Kq9Zx2mV7pL4nR8tW1y",
"type": "shop.purchase",
"createdAt": "2026-10-07T12:00:00.000Z",
"guildId": "123456789012345678",
"data": {
"purchaseId": 98765,
"userId": "876543210987654321",
"item": {
"id": 98765,
"name": "Example",
"emoji": "🪙",
"type": "example"
},
"store": {
"id": 98765,
"name": "Example"
},
"price": 250,
"status": "example",
"roleId": "234567890123456789",
"expiresAt": "2026-10-07T12:00:00.000Z",
"createdAt": "2026-10-07T12:00:00.000Z"
}
}shop.refund 退款
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
purchaseId | integer | 是 | 至少 0 |
userId | string | 是 | Discord snowflake id Discord ID(字串) |
item | object | 是 | |
item.id | integer | null | 是 | null when the item was deleted since 至少 0 |
item.name | string | 是 | |
item.emoji | string | null | 是 | |
item.type | string | 是 | role | color | item | … |
price | integer | 是 | 至少 0 |
refundedBy | string | null | 是 | Discord snowflake id Discord ID(字串) |
refundedAt | string | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
{
"id": "evt_3Kq9Zx2mV7pL4nR8tW1y",
"type": "shop.refund",
"createdAt": "2026-10-07T12:00:00.000Z",
"guildId": "123456789012345678",
"data": {
"purchaseId": 98765,
"userId": "876543210987654321",
"item": {
"id": 98765,
"name": "Example",
"emoji": "🪙",
"type": "example"
},
"price": 250,
"refundedBy": "234567890123456789",
"refundedAt": "2026-10-07T12:00:00.000Z"
}
}tickets.opened 客服單已開啟
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
ticketId | integer | 是 | 至少 0 |
number | integer | 是 | |
userId | string | 是 | Discord snowflake id Discord ID(字串) |
panelId | integer | null | 是 | 至少 0 |
channelId | string | null | 是 | Discord snowflake id Discord ID(字串) |
subject | string | null | 是 | |
openedAt | string | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
{
"id": "evt_3Kq9Zx2mV7pL4nR8tW1y",
"type": "tickets.opened",
"createdAt": "2026-10-07T12:00:00.000Z",
"guildId": "123456789012345678",
"data": {
"ticketId": 98765,
"number": 7,
"userId": "876543210987654321",
"panelId": 98765,
"channelId": "234567890123456789",
"subject": "Help with my order",
"openedAt": "2026-10-07T12:00:00.000Z"
}
}tickets.closed 客服單已關閉
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
ticketId | integer | 是 | 至少 0 |
number | integer | 是 | |
userId | string | 是 | Discord snowflake id Discord ID(字串) |
panelId | integer | null | 是 | 至少 0 |
channelId | string | null | 是 | Discord snowflake id Discord ID(字串) |
closedBy | string | null | 是 | Discord snowflake id Discord ID(字串) |
closeReason | string | null | 是 | |
closeType | string | null | 是 | manual | auto | leave | … |
openedAt | string | null | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
closedAt | string | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
{
"id": "evt_3Kq9Zx2mV7pL4nR8tW1y",
"type": "tickets.closed",
"createdAt": "2026-10-07T12:00:00.000Z",
"guildId": "123456789012345678",
"data": {
"ticketId": 98765,
"number": 7,
"userId": "876543210987654321",
"panelId": 98765,
"channelId": "234567890123456789",
"closedBy": "234567890123456789",
"closeReason": "example",
"closeType": "example",
"openedAt": "2026-10-07T12:00:00.000Z",
"closedAt": "2026-10-07T12:00:00.000Z"
}
}members.joined 成員加入
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
userId | string | 是 | Discord snowflake id Discord ID(字串) |
bot | boolean | 是 | |
joinedAt | string | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
accountCreatedAt | string | null | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
{
"id": "evt_3Kq9Zx2mV7pL4nR8tW1y",
"type": "members.joined",
"createdAt": "2026-10-07T12:00:00.000Z",
"guildId": "123456789012345678",
"data": {
"userId": "876543210987654321",
"bot": false,
"joinedAt": "2026-10-07T12:00:00.000Z",
"accountCreatedAt": "2026-10-07T12:00:00.000Z"
}
}members.left 成員離開
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
userId | string | 是 | Discord snowflake id Discord ID(字串) |
bot | boolean | 是 | |
leftAt | string | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
{
"id": "evt_3Kq9Zx2mV7pL4nR8tW1y",
"type": "members.left",
"createdAt": "2026-10-07T12:00:00.000Z",
"guildId": "123456789012345678",
"data": {
"userId": "876543210987654321",
"bot": false,
"leftAt": "2026-10-07T12:00:00.000Z"
}
}giveaways.ended 抽獎已結束
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
giveawayId | integer | 是 | 至少 0 |
prize | string | 是 | |
channelId | string | null | 是 | Discord snowflake id Discord ID(字串) |
messageId | string | null | 是 | Discord snowflake id Discord ID(字串) |
hostId | string | null | 是 | Discord snowflake id Discord ID(字串) |
winnerIds | array of string | 是 | |
entrants | integer | 是 | 至少 0 |
endedAt | string | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
{
"id": "evt_3Kq9Zx2mV7pL4nR8tW1y",
"type": "giveaways.ended",
"createdAt": "2026-10-07T12:00:00.000Z",
"guildId": "123456789012345678",
"data": {
"giveawayId": 98765,
"prize": "Nitro",
"channelId": "234567890123456789",
"messageId": "234567890123456789",
"hostId": "234567890123456789",
"winnerIds": [
"234567890123456789"
],
"entrants": 42,
"endedAt": "2026-10-07T12:00:00.000Z"
}
}moderation.caseCreated 管理案件
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
caseId | integer | 是 | 至少 0 |
number | integer | 是 | |
action | string | 是 | warn | timeout | kick | ban | tempban | unban | … |
targetId | string | 是 | Discord snowflake id Discord ID(字串) |
moderatorId | string | null | 是 | Discord snowflake id Discord ID(字串) |
reason | string | null | 是 | |
durationSeconds | integer | null | 是 | 至少 0 |
source | string | null | 是 | |
expiresAt | string | null | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
createdAt | string | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
{
"id": "evt_3Kq9Zx2mV7pL4nR8tW1y",
"type": "moderation.caseCreated",
"createdAt": "2026-10-07T12:00:00.000Z",
"guildId": "123456789012345678",
"data": {
"caseId": 98765,
"number": 7,
"action": "example",
"targetId": "234567890123456789",
"moderatorId": "234567890123456789",
"reason": "Tournament prize",
"durationSeconds": 3600,
"source": "example",
"expiresAt": "2026-10-07T12:00:00.000Z",
"createdAt": "2026-10-07T12:00:00.000Z"
}
}applications.submitted 已提交申請
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
submissionId | integer | 是 | 至少 0 |
number | integer | 是 | |
userId | string | 是 | Discord snowflake id Discord ID(字串) |
formId | integer | null | 是 | 至少 0 |
formTitle | string | null | 是 | |
status | string | 是 | |
answers | array of object | 是 | |
answers[].questionId | string | 是 | |
answers[].label | string | 是 | |
answers[].type | string | 是 | Question type, e.g. short, paragraph, select, number, yesno |
answers[].value | string | null | 是 | |
answers[].text | string | null | 是 | Human-readable answer (as shown in Discord), or null |
submittedAt | string | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
{
"id": "evt_3Kq9Zx2mV7pL4nR8tW1y",
"type": "applications.submitted",
"createdAt": "2026-10-07T12:00:00.000Z",
"guildId": "123456789012345678",
"data": {
"submissionId": 98765,
"number": 7,
"userId": "876543210987654321",
"formId": 98765,
"formTitle": "example",
"status": "example",
"answers": [
{
"questionId": "234567890123456789",
"label": "Example",
"type": "example",
"value": "example",
"text": "Example answer"
}
],
"submittedAt": "2026-10-07T12:00:00.000Z"
}
}appeals.submitted 已提交停權申訴
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
appealId | integer | 是 | 至少 0 |
number | integer | 是 | |
userId | string | 是 | Discord snowflake id Discord ID(字串) |
banCaseNumber | integer | null | 是 | |
banReason | string | null | 是 | |
answers | array of object | 是 | |
answers[].questionId | string | 是 | |
answers[].label | string | 是 | |
answers[].type | string | 是 | Question type, e.g. short, paragraph, select, number, yesno |
answers[].value | string | null | 是 | |
answers[].text | string | null | 是 | Human-readable answer (as shown in Discord), or null |
createdAt | string | 是 | ISO-8601 timestamp (UTC) ISO 8601 日期時間(UTC) |
{
"id": "evt_3Kq9Zx2mV7pL4nR8tW1y",
"type": "appeals.submitted",
"createdAt": "2026-10-07T12:00:00.000Z",
"guildId": "123456789012345678",
"data": {
"appealId": 98765,
"number": 7,
"userId": "876543210987654321",
"banCaseNumber": 10,
"banReason": "example",
"answers": [
{
"questionId": "234567890123456789",
"label": "Example",
"type": "example",
"value": "example",
"text": "Example answer"
}
],
"createdAt": "2026-10-07T12:00:00.000Z"
}
}