GameSO API

Appearance

Merchant Webhook API ​

จัดการ Webhook URL สำหรับรับ notification เมื่อ order มีการเปลี่ยนแปลงสถานะ รองรับหลาย URLs ต่อ 1 Merchant

Endpoints ​

MethodEndpointคำอธิบาย
GET/v1/merchant-webhooksดูรายการ webhook ทั้งหมด
POST/v1/merchant-webhooksสร้าง webhook ใหม่
GET/v1/merchant-webhooks/{id}ดู webhook รายการเดียว
PATCH/v1/merchant-webhooks/{id}แก้ไข webhook
DELETE/v1/merchant-webhooks/{id}ลบ webhook

Authentication ​

ทุก endpoint ต้องส่ง X-API-Key header — ดู Authentication

1. GET /v1/merchant-webhooks ​

ดึงรายการ webhook configurations ทั้งหมดของ Merchant

Request

http
GET /v1/merchant-webhooks
X-API-Key: your_api_key_here

Response 200 OK

json
[
    {
        "id": 1,
        "url": "https://merchant.example.com/webhooks/orders",
        "events": ["order.completed", "order.failed"],
        "secret_hint": "a1b2c3d4...",
        "status": "active",
        "max_retries": 3,
        "retry_delay": 60,
        "created_at": "2025-01-10T08:00:00.000Z",
        "updated_at": "2025-01-10T08:00:00.000Z"
    },
    {
        "id": 2,
        "url": "https://backup.example.com/webhooks",
        "events": ["order.completed"],
        "secret_hint": "z9y8x7w6...",
        "status": "inactive",
        "max_retries": 3,
        "retry_delay": 60,
        "created_at": "2025-01-12T10:00:00.000Z",
        "updated_at": "2025-01-15T09:00:00.000Z"
    }
]

TIP

secret_hint แสดงเพียง 8 ตัวอักษรแรกของ secret เพื่อความปลอดภัย ไม่สามารถดู secret เต็มได้หลังจากสร้างแล้ว

2. POST /v1/merchant-webhooks ​

สร้าง webhook URL ใหม่สำหรับรับ notification

Request Body

json
{
    "url": "https://merchant.example.com/webhooks/orders",
    "secret": "your-secret-key-min-16-chars"
}

Request Parameters

FieldTypeRequiredDescription
urlstring (URI)✅Webhook endpoint URL (แนะนำ HTTPS)
secretstring❌Secret key สำหรับ HMAC signature (16–255 ตัวอักษร) ถ้าไม่ระบุระบบจะสร้างให้อัตโนมัติ

Secret Key

บันทึก secret ไว้ทันทีหลังสร้าง — ระบบจะแสดงเฉพาะ secret_hint (8 ตัวแรก) ในครั้งถัดไป ไม่สามารถดู secret เต็มได้อีก

Response 201 Created

json
{
    "id": 3,
    "url": "https://merchant.example.com/webhooks/orders",
    "events": ["order.completed", "order.failed"],
    "secret_hint": "your-sec...",
    "status": "active",
    "max_retries": 3,
    "retry_delay": 60,
    "created_at": "2025-01-15T10:00:00.000Z",
    "updated_at": "2025-01-15T10:00:00.000Z"
}

Error 400 Bad Request (URL ไม่ถูกต้อง หรือ secret สั้นเกินไป)

json
{
    "status": 400,
    "code": "BAD_REQUEST",
    "message": "secret must be at least 16 characters"
}

ตัวอย่าง POST

bash
curl -X POST https://api.gameso.io/v1/merchant-webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "url": "https://merchant.example.com/webhooks/orders",
    "secret": "my-super-secret-key-2025"
  }'
javascript
const response = await fetch("https://api.gameso.io/v1/merchant-webhooks", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.GAMESO_API_KEY,
    },
    body: JSON.stringify({
        url: "https://merchant.example.com/webhooks/orders",
        secret: process.env.WEBHOOK_SECRET, // ควรเก็บใน env
    }),
});

const webhook = await response.json();
console.log("Webhook ID:", webhook.id);
// บันทึก webhook.id ไว้สำหรับแก้ไข/ลบในอนาคต
python
import requests, os

response = requests.post(
    'https://api.gameso.io/v1/merchant-webhooks',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['GAMESO_API_KEY'],
    },
    json={
        'url': 'https://merchant.example.com/webhooks/orders',
        'secret': os.environ['WEBHOOK_SECRET'],
    }
)

webhook = response.json()
print(f"Webhook ID: {webhook['id']}")

3. GET webhook by ID ​

ดูข้อมูล webhook configuration รายการเดียว

Path Parameter

ParameterTypeRequiredDescription
idinteger✅Webhook ID

Request

http
GET /v1/merchant-webhooks/1
X-API-Key: your_api_key_here

Response 200 OK

json
{
    "id": 1,
    "url": "https://merchant.example.com/webhooks/orders",
    "events": ["order.completed", "order.failed"],
    "secret_hint": "a1b2c3d4...",
    "status": "active",
    "max_retries": 3,
    "retry_delay": 60,
    "created_at": "2025-01-10T08:00:00.000Z",
    "updated_at": "2025-01-10T08:00:00.000Z"
}

Error 404 Not Found

json
{
    "status": 404,
    "code": "NOT_FOUND",
    "message": "Webhook not found"
}

4. PATCH webhook by ID ​

แก้ไข webhook URL, status หรือ secret ของรายการที่ระบุ ส่งเฉพาะ field ที่ต้องการแก้ไข (partial update)

Path Parameter

ParameterTypeRequiredDescription
idinteger✅Webhook ID

Request Body

json
{
    "url": "https://new-endpoint.example.com/webhooks",
    "secret": "new-secret-key-at-least-16",
    "status": "inactive"
}

Request Parameters

FieldTypeRequiredDescription
urlstring (URI)❌URL ใหม่
secretstring❌Secret ใหม่ (16–255 ตัวอักษร)
statusstring❌active หรือ inactive

Response 200 OK

json
{
    "id": 1,
    "url": "https://new-endpoint.example.com/webhooks",
    "events": ["order.completed", "order.failed"],
    "secret_hint": "new-secr...",
    "status": "inactive",
    "max_retries": 3,
    "retry_delay": 60,
    "created_at": "2025-01-10T08:00:00.000Z",
    "updated_at": "2025-01-15T12:00:00.000Z"
}

ตัวอย่าง PATCH

bash
curl -X PATCH https://api.gameso.io/v1/merchant-webhooks/1 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{ "status": "inactive" }'
javascript
// ปิด webhook ชั่วคราว
await fetch("https://api.gameso.io/v1/merchant-webhooks/1", {
    method: "PATCH",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.GAMESO_API_KEY,
    },
    body: JSON.stringify({ status: "inactive" }),
});

// เปลี่ยน URL
await fetch("https://api.gameso.io/v1/merchant-webhooks/1", {
    method: "PATCH",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.GAMESO_API_KEY,
    },
    body: JSON.stringify({
        url: "https://new-endpoint.example.com/webhooks",
    }),
});

5. DELETE webhook by ID ​

ลบ webhook configuration รายการที่ระบุ

Path Parameter

ParameterTypeRequiredDescription
idinteger✅Webhook ID

Request

http
DELETE /v1/merchant-webhooks/1
X-API-Key: your_api_key_here

Response 200 OK

json
{
    "success": true,
    "message": "Webhook deleted successfully"
}

Error 404 Not Found

json
{
    "status": 404,
    "code": "NOT_FOUND",
    "message": "Webhook not found"
}

ตัวอย่าง DELETE

bash
curl -X DELETE https://api.gameso.io/v1/merchant-webhooks/1 \
  -H "X-API-Key: your_api_key_here"
javascript
const response = await fetch("https://api.gameso.io/v1/merchant-webhooks/1", {
    method: "DELETE",
    headers: {
        "X-API-Key": process.env.GAMESO_API_KEY,
    },
});

const result = await response.json();
if (result.success) {
    console.log("Webhook deleted");
}

Webhook Response Fields ​

FieldTypeDescription
idintegerWebhook ID (ใช้สำหรับ update/delete)
urlstringWebhook endpoint URL
eventsarrayEvents ที่ subscribe: order.completed, order.failed
secret_hintstring8 ตัวอักษรแรกของ secret (เพื่อยืนยันว่าใช้ secret ถูกต้อง)
statusstringactive หรือ inactive
max_retriesintegerจำนวนครั้งสูงสุดที่ retry เมื่อ delivery ล้มเหลว
retry_delayintegerระยะเวลา (วินาที) ระหว่างการ retry
created_atstringวันเวลาที่สร้าง (ISO 8601)
updated_atstringวันเวลาที่แก้ไขล่าสุด (ISO 8601)

แนวทางการใช้งาน ​

ตั้งค่าครั้งแรก

javascript
// 1. สร้าง webhook
const webhook = await createWebhook({
    url: "https://your-server.com/webhooks/gameso",
    secret: process.env.WEBHOOK_SECRET,
});

// 2. บันทึก ID ไว้
console.log("Save this ID:", webhook.id);

// 3. ทดสอบโดยสร้าง order และรอ webhook

Rotate Secret

javascript
// สร้าง secret ใหม่โดยไม่ต้องลบ webhook
await fetch(`https://api.gameso.io/v1/merchant-webhooks/${webhookId}`, {
    method: "PATCH",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.GAMESO_API_KEY,
    },
    body: JSON.stringify({
        secret: newSecret,
    }),
});

TIP

ดูรายละเอียดเพิ่มเติมเกี่ยวกับ Webhook Payload และการตรวจสอบ Signature ได้ที่ Webhook Payload & Signature

GameSO API Documentation

© 2025 GameSO. All rights reserved.