Whitelist API และ Webhooks

จัดการ whitelist ของ instance จากเครื่องมือของคุณเอง: เพิ่มผู้เล่นพร้อมวันหมดอายุ, ตั้งหรือล้างวันหมดอายุทีละหลายคน, ลบผู้เล่น และรับ webhook ที่มีลายเซ็นทุกครั้งที่รายชื่อเปลี่ยน

เข้าถึงได้ 3 ทาง:

Base URL: https://api.neko-launcher.com/api/v1 คำตอบอยู่ในรูป { code, message, data } เอกสารแบบลองเรียกได้อยู่ที่ https://api.neko-launcher.com/docs

Routes

ทุก route ใช้ชื่อ instance (id ใน URL) แทน <name> ฝั่ง Server API มี route เขียนแบบเดียวกันที่ /server/instances/<name>/…

ดูรายชื่อ

GET /instances/<name>/whitelist

data คือทุก entry รวมที่หมดอายุแล้ว: id, matchType (uuid หรือ username), minecraftUuid, username, createdAt, expiresAt

เพิ่มผู้เล่น

POST /instances/<name>/whitelist

{ "value": "069a79f4-44e9-4726-a5be-fca90e38aaf5", "expiresAt": "2026-12-31T23:59:00+07:00" }
json

ตอบ 201 พร้อม entry, 409 ถ้าซ้ำ, 403 ถ้า whitelist เต็มโควตาแพ็กเกจ entry ที่หมดอายุไม่นับรวมในโควตา

ตั้งหรือล้างวันหมดอายุ 1 รายการ

PATCH /instances/<name>/whitelist/<id>
{ "expiresAt": "2026-12-31T23:59:00Z" }

null = ไม่มีวันหมดอายุ การตั้งวันใหม่ให้ entry ที่หมดอายุแล้วจะทำให้กลับมาใช้ได้และนับรวมโควตาอีกครั้ง

ตั้งหรือล้างวันหมดอายุหลายรายการ

PATCH /instances/<name>/whitelist/bulk
{ "ids": ["<id>", "<id>"], "expiresAt": "2026-12-31T23:59:00Z" }

สูงสุด 1000 id ต่อครั้ง id ของ instance อื่นจะถูกข้าม data คือ { "updated": <จำนวน>, "expiresAt": … } ถ้าการเปลี่ยนจะทำให้ entry ที่หมดอายุกลับมาเกินโควตา จะไม่มีอะไรเปลี่ยนและ API ตอบ 403

ลบผู้เล่น

DELETE /instances/<name>/whitelist/<id>
POST   /instances/<name>/whitelist/bulk-remove   { "ids": ["<id>", …] }

ลบหลายรายการได้สูงสุด 1000 id ตอบ { "removed": <จำนวน>, "ids": [...] }

Webhooks

ส่งการเปลี่ยนแปลงของ whitelist และใบสมัครไปยังระบบของคุณ เช่น sync เซิร์ฟเวอร์เกม หรือโพสต์ผ่านบอต Discord

Webhook เป็นของ workspace เพิ่มได้ในแดชบอร์ดที่ Developer → Webhooks:

1. วาง URL ปลายทางแล้วกด ทดสอบ แดชบอร์ดจะส่ง ping และแสดงผลตอบกลับ
2. เลือก event และจะจำกัดเฉพาะบาง instance ก็ได้
3. บันทึก แล้วคัดลอก signing secret (whsec_…) ซึ่งแสดงครั้งเดียว กด Rotate secret เพื่อออกอันใหม่

สร้างได้สูงสุด 10 webhook ต่อ workspace URL ต้องเป็น HTTPS สาธารณะและไม่มี credentials แดชบอร์ดแสดงการส่ง 50 ครั้งล่าสุดของแต่ละ webhook พร้อมสถานะ

Webhook ที่เคยตั้งไว้ใน instance ก่อนตุลาคม 2026 (Whitelist → Webhook on whitelist changes) ถูกย้ายมาเป็น webhook ของ workspace พร้อม event whitelist ทั้งสามให้อัตโนมัติ และตอนนี้ได้รับคำขอแบบมีลายเซ็นด้วย

Events

แต่ละ event เป็น HTTPS POST แบบ content-type: application/json พร้อม header:

การเปลี่ยนแบบหลายรายการจะส่งทีละ entry ต่อกันไป

{
  "event": "whitelist.updated",
  "deliveryId": "3f0c9a…",
  "occurredAt": "2026-10-02T10:00:00.000Z",
  "instance": { "name": "koyo-7f3a", "displayName": "KoyoSMP" },
  "player": { "matchType": "uuid", "username": "Notch", "uuid": "069a79f444e94726a5befca90e38aaf5" },
  "whitelist": { "createdAt": "2026-09-01T08:00:00.000Z", "expiresAt": "2026-12-31T16:59:00.000Z" }
}
json

event ของใบสมัครและการชำระเงินมี "application": { "id", "applicantUsername", "applicantUuid", "reviewNote"?, "fee"?, "deadline"? } แทน player และ whitelist

ตรวจลายเซ็น

คำนวณ HMAC จาก body ดิบ ตามที่ได้รับ (ก่อน parse JSON) เทียบแบบ constant time และปฏิเสธ timestamp ที่เก่าเกินไม่กี่นาที เพื่อกันการนำคำขอที่ถูกดักไปส่งซ้ำ

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, headers, secret) {
  const ts = headers['x-neko-timestamp'];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const got = String(headers['x-neko-signature'] ?? '');
  return got.length === expected.length && timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}
js

SDK ทำให้ได้ด้วย constructEvent()

การส่ง

ส่งแบบ best-effort: แต่ละคำขอ timeout ที่ 5 วินาทีและไม่ส่งซ้ำ ให้ตอบ 2xx ให้เร็วแล้วค่อยทำงานต่อ ถ้าห้ามพลาดเลย ให้ดึงรายชื่อเป็นระยะด้วย Server API ด้วย

Loading diagram…

MCP tools

ผู้ช่วย AI ที่เชื่อมผ่าน MCP (https://api.neko-launcher.com/api/v1/mcp) ทำได้แบบเดียวกัน:

ต้องมีสิทธิ์ players บนการเชื่อมต่อ และแพ็กเกจ workspace ต้องเปิด web MCP

ดูเพิ่ม

• Server API และ SDK
• Whitelist ใบสมัคร และลิงก์เชิญ