> For the complete documentation index, see [llms.txt](https://docs.ggwp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ggwp.com/chinese-simplified/webhook/ding-yue-api.md).

# 订阅 API

\[ 基础 URL: `api.ggwp.com` ]

## **身份验证**

请参阅 [此处的章节](/chinese-simplified/api-wen-dang-liao-tian/biao-zhun-tao-can.md#authentication) 进行身份验证。

## **新版本 v1.1**

新版本 `1.1` 已发布，包含一些小改动。

更新日志：

* 新的 webhook 事件订阅将默认设为该 `1.1` 版本
* 发送到 webhook URL 的事件，其载荷将以不含空白字符的字符串格式发送
* 注意：对版本 `1.0` 将继续。该版本在计算用于 [载荷验证](/chinese-simplified/webhook/jie-shou-shi-jian.md#request-validation).

## **API**

### **1. 订阅一个事件**

`POST` /webhook/v1/subscriptions

此 API 可将客户订阅到由 GGWP 平台生成的事件。

**参数**

* **url：** 事件触发时接收调用的 URL
* **enabled：** 布尔值 `true` 或 `false` 表示 webhook 是否应处于启用状态。默认值为 `true` 如果未传递。
* **event\_type：** 要订阅的事件类型，如下所述 [Webhook 事件](/chinese-simplified/webhook/webhook-shi-jian.md)
* **version：** 表示载荷版本。默认值为 `1.1` 如果未传递。
* （可选） **headers：** 表示请求头名称和值的键值对。
  * 请求头名称只能包含字母、数字和连字符。
  * 请求头名称最长可达 256 个字符，值最长可达 1024 个字符。
  * 以下请求头为保留项，不被接受
    * `content-type`
    * `x-ggwp-hmac-sha256`
    * `host`
    * `content-length`
    * `connection`
    * `transfer-encoding`
    * `expect`

示例：

{% code overflow="wrap" %}

```json
{
	"url": "https://example.com/customerapi",
	"enabled": true,
	"event_type": "player-sanctioned",
	"version": "1.1",
	"headers": {
	    "Authorization": "Bearer <JWT_TOKEN>"
	}
}
```

{% endcode %}

**输出**

* 201

{% code overflow="wrap" %}

```json
{
	"id": "85537238-1053-4057-877e-131838c789d8",
	"url": "https://example.com/customerapi",
	"enabled": true,
	"event_type": "player-sanctioned",
	"version": "1.1",
	"headers": {
	    "Authorization": "Bearer <JWT_TOKEN>"
	},
	"created_at": "2024-02-27T17:02:39",
	"updated_at": "2024-02-27T17:02:39",
	"secret_key": "xxxxxxxxxxxxxx"
}
```

{% endcode %}

该 `secret_key` 在本次请求中返回的内容应由客户端保存。每个订阅都会有其自己独特的 `secret_key`。这用于验证该 URL 是否由合法方调用，在本例中即 GGWP。更多内容请参见 [接收事件](/chinese-simplified/webhook/jie-shou-shi-jian.md) 部分。

* 400
  * 如果以下任一字段缺失： `url`, `event_type`
  * 发送的 URL 格式不正确 `url` 参数
  * 无效的 `event_type` 已发送
  * 无效的 `版本` 已发送
  * 无效的 `enabled` 已发送
  * 无效的 `请求头` 已发送
* 403
  * 无效或缺失的 API 密钥
* 500

  * 服务器端出了点问题。请求可在几分钟后再次重试。如果问题持续存在，请联系你的 GGWP 客户经理。

### 2. 列出所有订阅

`GET` /webhook/v1/subscriptions

该 API 列出客户已订阅的所有 webhook。它不会返回 `secret_key` 。不过，请查看下面的列表以了解用于获取 secret key 的 API GET。

**输出**

* 200

{% code overflow="wrap" %}

```json
[
	{
		"id": "85537238-1053-4057-877e-131838c789d8",
		"url": "https://example.com/customerapi",
		"enabled": true,
		"event_type": "player-sanctioned",
		"version": "1.1",
		"headers": {
		    "Authorization": "Bearer <JWT_TOKEN>"
		},
		"created_at": "2024-02-27T16:16:25",
		"updated_at": "2024-02-27T16:16:25"
	},
	{
		"id": "de48a6a4-8bb6-470e-9990-2fd83f3ccbb5",
		"url": "https://example.com/customerapi",
		"enabled": true,
		"event_type": "player-reinstated",
		"version": "1.1",
		"headers": {},
		"created_at": "2024-02-27T16:16:25",
		"updated_at": "2024-02-27T16:16:25"
	},
	...
]
```

{% endcode %}

* 403
  * 无效或缺失的 API 密钥

### 3. 更新订阅

`PATCH` /webhook/v1/subscriptions/:id

更新 webhook 订阅属性。&#x20;

**参数**

* **id：** 作为路径参数传递。这是要修改的事件订阅 ID。
* **event\_type：** 将事件类型更新为列表中的其他事件 [这里](/chinese-simplified/webhook/webhook-shi-jian.md)
* **url：** 更新用于在事件触发时接收调用的 URL
* **enabled：** 通过发送 `true` 或 `false`
* **version：** 更改订阅服务的版本。
* （可选） **headers：** 表示请求头名称和值的键值对。

示例：

{% code overflow="wrap" %}

```json
{
	"event_type": "player-sanctioned",
	"url": "https://example.com/customerapi",
	"enabled": true,
	"version": "1.1",
	"headers": {
	    "Authorization": "Bearer <JWT_TOKEN>"
	}
}
```

{% endcode %}

**输出**

* 200

{% code overflow="wrap" %}

```json
{
	"id": "85537238-1053-4057-877e-131838c789d8",
	"url": "https://example.com/customerapi",
	"enabled": true,
	"event_type": "player-sanctioned",
	"version": "1.1",
	"headers": {
	    "Authorization": "Bearer <JWT_TOKEN>"
	},
	"created_at": "2024-02-27T16:16:25",
	"updated_at": "2024-02-27T16:16:25"
}
```

{% endcode %}

* 400
  * 无效的 `event_type` 已发送
  * 无效的 `版本` 已发送
  * 无效的 `enabled` 已发送
  * 无效的 `请求头` 已发送
* 403
  * 无效或缺失的 API 密钥
* 500

  * 服务器端出了点问题。请求可在几分钟后再次重试。如果问题持续存在，请联系你的 GGWP 客户经理。

### **4. 删除订阅**

`DELETE` /webhook/v1/subscriptions/:id

删除指定 ID 的订阅。

**参数**

* **id：** 作为路径参数传递。这是要删除的事件订阅 ID。

**输出**

* 200

{% code overflow="wrap" %}

```json
{"success": true}
```

{% endcode %}

* 403
  * 无效或缺失的 API 密钥
* 404
  * 未找到订阅
* 500

  * 服务器端出了点问题。请求可在几分钟后再次重试。如果问题持续存在，请联系你的 GGWP 客户经理。

### **5. 轮换 Secret**

`POST` /webhook/v1/subscriptions/:id/secret

轮换订阅 secret key。API 调用成功后，secret key 会立即更新。

**参数**

* **id：** 作为路径参数传递。这是要轮换其密钥的订阅 ID

**输出**

* 200

{% code overflow="wrap" %}

```json
{
	"secret_key": "yyyyyyyyyyyyyy"
}
```

{% endcode %}

* 403
  * 无效或缺失的 API 密钥
* 500

  * 服务器端出了点问题。请求可在几分钟后再次重试。如果问题持续存在，请联系你的 GGWP 客户经理。

### **6. 获取 Secret**

`GET` /webhook/v1/subscriptions/:id/secret

返回指定订阅的 secret key `id`

**参数**

* **id：** 作为路径参数传递。这是请求其 secret key 的订阅 ID

**输出**

* 200

{% code overflow="wrap" %}

```json
{
	"secret_key": "yyyyyyyyyyyyyy"
}
```

{% endcode %}

* 403
  * 无效或缺失的 API 密钥