REST API v1 · 開發者

Webhook:把 Discord 伺服器事件直接送到你的伺服器

不必再反覆輪詢 API,讓 BotGG 主動通知你:當 Discord 伺服器發生事情時,例如餘額變動、升級、購買或新的客服單,BotGG 會向你的 HTTPS 端點送出一個有簽章的 JSON POST 請求。

開發者文件
本頁目錄

設定端點

  1. 在控制台中開啟伺服器的 API 區塊,新增一個 Webhook 端點:填入 https:// 網址,並選擇想接收的事件。
  2. 複製簽章密鑰(whsec_…),它只會顯示一次,請儲存在你的伺服器上,例如存成 BOTGG_WEBHOOK_SECRET。
  3. 從控制台傳送一個測試事件,事件類型為 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>")>。

  1. 讀取完全未經處理、與收到時一模一樣的原始內容(在任何 JSON 解析之前)。
  2. 如果 BotGG-Webhook-Timestamp 與你的系統時間相差超過 5 分鐘,就拒絕該請求,這樣可以防止重放攻擊。
  3. 用你的密鑰計算 <timestamp>.<原始內容> 的 HMAC,並以固定時間比較的方式,與 BotGG-Signature 中的每個 v1= 值比對。
Node.js (Express)
// 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 (Flask)
# 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(交易、購買、客服單等)則是整數。

Webhook 事件
事件功能說明
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 銀行交易
bank.transaction 的 `data` 欄位
欄位類型必填說明
transactionIdinteger是至少 0
userIdstring是Discord snowflake id
Discord ID(字串)
typestring是Ledger type: daily, transfer_in, transfer_out, fee, admin_add, admin_remove, admin_set, flow, api, …
amountinteger是Signed change (negative = debit)
balanceAfterinteger是
reasonstring | null是
counterpartyIdstring | null是Discord snowflake id
Discord ID(字串)
actorIdstring | null是Discord snowflake id
Discord ID(字串)
createdAtstring是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 升級
levels.levelUp 的 `data` 欄位
欄位類型必填說明
userIdstring是Discord snowflake id
Discord ID(字串)
levelinteger是至少 0
previousLevelinteger是至少 0
sourcestring是其中之一 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 購買
shop.purchase 的 `data` 欄位
欄位類型必填說明
purchaseIdinteger是至少 0
userIdstring是Discord snowflake id
Discord ID(字串)
itemobject是
item.idinteger | null是null when the item was deleted since
至少 0
item.namestring是
item.emojistring | null是
item.typestring是role | color | item | …
storeobject是id/name null = the built-in Main store
store.idinteger | null是至少 0
store.namestring | null是
priceinteger是至少 0
statusstring是owned | used | refunded
roleIdstring | null是Discord snowflake id
Discord ID(字串)
expiresAtstring | null是ISO-8601 timestamp (UTC)
ISO 8601 日期時間(UTC)
createdAtstring是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 退款
shop.refund 的 `data` 欄位
欄位類型必填說明
purchaseIdinteger是至少 0
userIdstring是Discord snowflake id
Discord ID(字串)
itemobject是
item.idinteger | null是null when the item was deleted since
至少 0
item.namestring是
item.emojistring | null是
item.typestring是role | color | item | …
priceinteger是至少 0
refundedBystring | null是Discord snowflake id
Discord ID(字串)
refundedAtstring是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 客服單已開啟
tickets.opened 的 `data` 欄位
欄位類型必填說明
ticketIdinteger是至少 0
numberinteger是
userIdstring是Discord snowflake id
Discord ID(字串)
panelIdinteger | null是至少 0
channelIdstring | null是Discord snowflake id
Discord ID(字串)
subjectstring | null是
openedAtstring是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 客服單已關閉
tickets.closed 的 `data` 欄位
欄位類型必填說明
ticketIdinteger是至少 0
numberinteger是
userIdstring是Discord snowflake id
Discord ID(字串)
panelIdinteger | null是至少 0
channelIdstring | null是Discord snowflake id
Discord ID(字串)
closedBystring | null是Discord snowflake id
Discord ID(字串)
closeReasonstring | null是
closeTypestring | null是manual | auto | leave | …
openedAtstring | null是ISO-8601 timestamp (UTC)
ISO 8601 日期時間(UTC)
closedAtstring是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 成員加入
members.joined 的 `data` 欄位
欄位類型必填說明
userIdstring是Discord snowflake id
Discord ID(字串)
botboolean是
joinedAtstring是ISO-8601 timestamp (UTC)
ISO 8601 日期時間(UTC)
accountCreatedAtstring | 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 成員離開
members.left 的 `data` 欄位
欄位類型必填說明
userIdstring是Discord snowflake id
Discord ID(字串)
botboolean是
leftAtstring是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 抽獎已結束
giveaways.ended 的 `data` 欄位
欄位類型必填說明
giveawayIdinteger是至少 0
prizestring是
channelIdstring | null是Discord snowflake id
Discord ID(字串)
messageIdstring | null是Discord snowflake id
Discord ID(字串)
hostIdstring | null是Discord snowflake id
Discord ID(字串)
winnerIdsarray of string是
entrantsinteger是至少 0
endedAtstring是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 管理案件
moderation.caseCreated 的 `data` 欄位
欄位類型必填說明
caseIdinteger是至少 0
numberinteger是
actionstring是warn | timeout | kick | ban | tempban | unban | …
targetIdstring是Discord snowflake id
Discord ID(字串)
moderatorIdstring | null是Discord snowflake id
Discord ID(字串)
reasonstring | null是
durationSecondsinteger | null是至少 0
sourcestring | null是
expiresAtstring | null是ISO-8601 timestamp (UTC)
ISO 8601 日期時間(UTC)
createdAtstring是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 已提交申請
applications.submitted 的 `data` 欄位
欄位類型必填說明
submissionIdinteger是至少 0
numberinteger是
userIdstring是Discord snowflake id
Discord ID(字串)
formIdinteger | null是至少 0
formTitlestring | null是
statusstring是
answersarray of object是
answers[].questionIdstring是
answers[].labelstring是
answers[].typestring是Question type, e.g. short, paragraph, select, number, yesno
answers[].valuestring | null是
answers[].textstring | null是Human-readable answer (as shown in Discord), or null
submittedAtstring是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 已提交停權申訴
appeals.submitted 的 `data` 欄位
欄位類型必填說明
appealIdinteger是至少 0
numberinteger是
userIdstring是Discord snowflake id
Discord ID(字串)
banCaseNumberinteger | null是
banReasonstring | null是
answersarray of object是
answers[].questionIdstring是
answers[].labelstring是
answers[].typestring是Question type, e.g. short, paragraph, select, number, yesno
answers[].valuestring | null是
answers[].textstring | null是Human-readable answer (as shown in Discord), or null
createdAtstring是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"
  }
}

常見問題

接收 Webhook 需要 API 金鑰嗎?

不需要。Webhook 是靠端點的簽章密鑰所產生的簽章來驗證。只有在你的伺服器同時也要呼叫 REST API 時,才需要 API 金鑰。

為什麼我的簽章驗證失敗?

通常是因為內容在計算雜湊之前,已經被解析並重新序列化。請對你收到的原始位元組計算 HMAC,並使用該端點的 whsec_… 密鑰,同時檢查你伺服器的時鐘。

如果我的伺服器當機會怎樣?

BotGG 會在大約 33 小時內,對每次傳送最多重試 7 次。如果端點長時間持續失敗就會被停用;問題修正後,可以從控制台重送失敗的事件。

準備好讓你的伺服器升級了嗎?

免費新增 BotGG,再到網頁控制台開啟需要的功能。