# General Translation Platform: Webhooks
URL: https://generaltranslation.com/ja/docs/platform/orgs/webhooks.mdx
---
title: Webhooks
description: 組織内でイベントが発生したときにリアルタイム通知を受け取る
---

Webhook を使うと、翻訳済みファイルの処理完了や翻訳ジョブの完了など、組織内でイベントが発生した際に、アプリケーションで HTTP POST リクエストを受信できます。

Webhook は **Team プラン** 以上で利用できます。

## Webhook の設定

1. **Organization Settings → Webhooks** に移動します
2. **Create Webhook** をクリックします
3. イベントを受信するエンドポイント URL を入力します (HTTPS である必要があります) 
4. 購読するイベントタイプを選択します
5. **Create** をクリックします

エンドポイントを作成したら、Webhook の詳細ページに移動して署名シークレットをコピーします。このシークレットは、受信したリクエストが General Translation から送信されたものであることを検証するために使用します。

1 つの組織につき、**Webhook エンドポイントは最大 5 個**まで作成できます。

## イベントタイプ

| Event                       | 説明                                       |
| --------------------------- | ---------------------------------------- |
| `translated_file.completed` | 翻訳済みファイルの生成が完了し、ダウンロードできるようになったときに発生します  |
| `translated_file.edited`    | 翻訳済みファイルが翻訳エディタでユーザーによって手動で編集されたときに発生します |
| `translation_job.completed` | 翻訳ジョブ が完了したときに発生します            |

各エンドポイントは、1 つ以上のイベントタイプを購読できます。サブスクリプションは webhook の詳細ページからいつでも更新できます。

## ペイロード形式

各 webhook 配信は、JSON ボディを含む HTTP POST リクエストです。

```json
{
  "id": "evt_xxx",
  "type": "translated_file.completed",
  "created_at": "2026-04-30T12:00:00.000Z",
  "api_version": "2026-03-06.v1",
  "data": {
    "object": {
      "id": "file_xxx",
      "org_id": "org_xxx",
      "project_id": "project_xxx",
      "branch_id": "branch_xxx",
      "source_file_id": "src_xxx",
      "file_id": "file_xxx",
      "version_id": "ver_xxx",
      "locale": "fr",
      "file_format": "json",
      "data_format": null,
      "completed_at": "2026-04-30T12:00:00.000Z"
    }
  }
}
```

最上位の `id` は安定したイベント識別子であり、ご利用のシステム側で配信の重複を排除するために使用できます。

## 署名の検証

各 webhook リクエストには、署名検証に使用する 3 つのヘッダーが含まれます。

| Header              | Description                     |
| ------------------- | ------------------------------- |
| `webhook-id`        | イベント ID (`evt_xxx`)             |
| `webhook-timestamp` | リクエストの送信時刻を表す Unix タイムスタンプ (秒)  |
| `webhook-signature` | `v1,<base64-hmac>` 形式の署名        |

署名は [Standard Webhooks](https://www.standardwebhooks.com/) の規約に従っています。検証するには、次の手順に従います。

1. `{webhook-id}.{webhook-timestamp}.{raw request body}` を連結します
2. 署名シークレットを使って HMAC-SHA256 を計算します (`whsec_` プレフィックスを削除してから、シークレットを base64 デコードします) 
3. 結果を base64 エンコードし、署名値 (`v1,` プレフィックスの後ろ) と比較します
4. リプレイ攻撃を防ぐため、タイムスタンプが現在時刻から 5 分以内であることを確認します

### 例 (Node.js) 

```js
import crypto from "crypto";

function verifyWebhook(payload, headers, secret) {
  const msgId = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signature = headers["webhook-signature"];

  // タイムスタンプの有効性を確認（許容誤差: 5分）
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    throw new Error("Timestamp too old");
  }

  // 期待される署名を計算
  const signingKey = Buffer.from(secret.replace("whsec_", ""), "base64");
  const signedContent = `${msgId}.${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", signingKey)
    .update(signedContent)
    .digest("base64");

  // 比較（定数時間）
  const received = signature.split(",")[1];
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
    throw new Error("Invalid signature");
  }

  return JSON.parse(payload);
}
```

ご利用の言語向けの [Standard Webhooks](https://www.standardwebhooks.com/) ライブラリを使用することもできます。このライブラリでは、検証が自動的に行われます。

## 再試行と配信

Webhook は **at-least-once delivery** を採用しています。エンドポイントが 10 秒以内に `2xx` レスポンスを返さない場合、配信は指数バックオフで再試行され、最大 **10 回**まで試行されます。

ダッシュボードの Webhook 詳細ページから、失敗した配信を手動で再試行することもできます。

### 重複への対応

at-least-once delivery であるため、エンドポイントが同じイベントを複数回受信することがあります。重複を排除するには、ペイロード内の `id` フィールドを使用します。

```js
app.post("/webhooks/gt", (req, res) => {
  const eventId = req.body.id;

  if (alreadyProcessed(eventId)) {
    return res.status(200).send("OK");
  }

  // イベントを処理する...
  markProcessed(eventId);
  res.status(200).send("OK");
});
```

## エンドポイントの管理

Webhook詳細ページでは、次の操作を行えます。

* エンドポイントを削除せずに**有効化/無効化**する
* 購読するイベントタイプを**更新**する
* **配信履歴を表示**し、個々の配信試行を確認する
* 失敗した配信を**再試行**する
* 署名シークレットを**表示**する (再コピー用) 
* エンドポイントを**削除**する

## ベストプラクティス

* **すばやく応答する** — できるだけ早く `2xx` レスポンスを返し、その後でイベントを非同期に処理します。長時間実行される handler はタイムアウトするおそれがあります。
* **署名を検証する** — ペイロードを信頼する前に、必ず `webhook-signature` ヘッダーを検証してください。
* **重複を処理する** — 処理済みのイベント ID を保存し、重複するイベントはスキップします。
* **HTTPS を使用する** — 本番環境では、webhook エンドポイントに HTTPS を使用する必要があります。
* **失敗を監視する** — エンドポイントの問題を示している可能性がある継続的な失敗がないか、配信履歴を定期的に確認してください。

## 権限

Webhook エンドポイントの管理には `org:webhooks:write` 権限が必要です。配信履歴の閲覧には `org:webhooks:read` 権限が必要です。デフォルトでは、**Owner** ロールと **Admin** ロールの両方に、これらの権限が付与されています。詳しくは、[Roles &amp; Permissions](/docs/platform/orgs/roles) を参照してください。