# Webhook

Webhook を使用すると、AI タスクが `success` または `error` ステータスで完了したときに、アプリケーションが非同期通知を受信できます。通知はあなたが管理する HTTP エンドポイントに送信され、[Standard Webhooks Specification](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md) に準拠しています。

#### Webhook シークレット

##### Webhook シークレットの構築

**HMAC-SHA256** 署名方式の Webhook シークレットを使用しています。Webhook シークレットは base64 エンコードされ、識別しやすいよう `whsec_` がプレフィックスとして付与されています。

Webhook シークレットの例:

`whsec_NDQzMzYxNzkzMzE0NjYyNDM6OTIxOTcwNDIxODQ`

##### Standard Webhooks ライブラリでの Webhook 実装

**Standard Webhooks Library** の公式実装の使用を推奨します。署名検証の詳細を気にする必要はありません。

公式実装を使用することで、安全かつ正確な署名検証が保証されます。

**[https://github.com/standard-webhooks/standard-webhooks/tree/main?tab=readme-ov-file#reference-implementations](https://github.com/standard-webhooks/standard-webhooks/tree/main?tab=readme-ov-file#reference-implementations)**

##### 自分で Webhook を実装する

Webhook シークレットの仕組みを理解してください。[Signature scheme](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md#signature-scheme) の Symmetric 部分を参照してください。

署名入力を署名する際は、`whsec_` プレフィックスを除去し、残りの文字列を base64 デコードしてシークレットの実際のバイトを取得してから、**HMAC-SHA256** ハッシュを実行します。

#### Webhook リクエスト例

```http
POST https://yourdomain.com/webhook-endpoint
Content-Type: application/json
webhook-id: msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848
webhook-timestamp: 1761112900
webhook-signature: v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0=
```

```json
{
  "created_at": 1761112848,
  "data": {
    "task_id": "1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4",
    "task_status": "success"
  }
}
```

#### HTTP ヘッダー

##### `webhook-id`

Webhook 配信の一意な識別子です。
この値はリトライ間で一貫しており、冪等性処理に使用すべきです。

##### `webhook-timestamp`

Webhook が送信されたときの Unix エポックタイムスタンプ（秒）です。

##### `webhook-signature`

'v1' の後にカンマ (,) が続き、その後に base64 エンコードされた **HMAC-SHA256** 署名が続きます。

'v1' は署名方式のバージョンを示し、現在サポートされている唯一のバージョンです。

base64 エンコードされた **HMAC-SHA256** 署名は、Webhook シークレットを使用して署名入力を署名した結果です。

署名入力形式:

```
{webhook-id}.{webhook-timestamp}.{raw-minified-json-body}
```

**署名済みコンテンツの例:**

```
msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848.1761112900.{"created_at":1761112848,"data":{"task_id":"1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4","task_status":"success"}}
```

#### リクエストボディ

##### `created_at`

タスクが完了した時刻を示す Unix エポックタイムスタンプ（秒）です。

##### `data`

イベントペイロードを含みます。

| フィールド | 説明 |
|  --- | --- |
| `task_id` | タスク作成時に返されたタスク識別子です。この ID を使用して最終的なタスク結果をクエリできます。 |
| `task_status` | タスク完了ステータス。可能な値: `success`、`error`。 |


## 統合ガイド

### Webhook 統合ガイド

1. **サーバーに Webhook エンドポイントを準備する。**
エンドポイントが `POST` リクエストを受け入れ、HTTPS 経由でアクセス可能であることを確認してください。
2. **API Console で Webhook を作成する。**
3. **AI タスクを実行し、`task_id` を記録する。**
4. **Webhook 通知を処理し、`task_id` を使用してタスク結果を取得する。**


#### Webhook エンドポイントの作成

API Console の Webhook 管理ページにアクセスします:

**[https://yce.makeupar.com/api-console/en/webhook/](https://yce.makeupar.com/api-console/en/webhook/)**

##### 1. Webhook セクションを見つける

![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webhook_main_bae171663b.png)

##### 2. 新しい Webhook エンドポイントを作成する

![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webhook_create_cd28e68fa3.png)

最大 **10 の Webhook エンドポイント** を同時に設定できます。

##### 3. Webhook シークレットを保護する

Webhook シークレットは `webhook-signature` の検証に使用されます。
安全に保管し、公開しないでください。

![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webhook_secret_key_6fe757a7de.png)

##### 4. 既存の Webhook を管理する

![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webhook_manage_endpoints_3bed715de9.png)

## 署名の検証

#### サーバーでの Webhook リクエストの処理

**Standard Webhooks Library** の公式実装の使用を推奨します:

**[https://github.com/standard-webhooks/standard-webhooks/tree/main?tab=readme-ov-file#reference-implementations](https://github.com/standard-webhooks/standard-webhooks/tree/main?tab=readme-ov-file#reference-implementations)**

これにより、安全かつ正確な署名検証が保証されます。

**Standard Webhooks Simulator** を使用してペイロードのテストやデバッグもできます:

**[https://www.standardwebhooks.com/simulate](https://www.standardwebhooks.com/simulate)**

#### Webhook 署名の検証

Webhook リクエスト例を検討します:

```http
POST https://yourdomain.com/webhook-endpoint
Content-Type: application/json
webhook-id: msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848
webhook-timestamp: 1761112900
webhook-signature: v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0=
```

リクエストボディ:

```json
{
  "created_at": 1761112848,
  "data": {
    "task_id": "1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4",
    "task_status": "success"
  }
}
```

署名入力形式は次のようになります:

```
{webhook-id}.{webhook-timestamp}.{raw-minified-json-body}
```

署名済みコンテンツの例:

```
msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848.1761112900.{"created_at":1761112848,"data":{"task_id":"1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4","task_status":"success"}}
```

受信した webhook-signature を使用して、Webhook シークレットキーで HMAC-SHA256 暗号化された署名済みコンテンツを検証します。
例:

```
v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0=
```