> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

> ポーリングを行う代わりに、プロジェクトがマイルストーンに達した瞬間にHTTPコールバックを受け取ります

# Webhook

Webhookを使用すると、何かが発生した瞬間にVoiceCheapがサーバーに通知できるため、ポーリングを停止できます
`GET /v1/translate/{projectId}/status`.

> [!NOTE]
>
> 配信は1回だけ試行され、再試行はありません。見逃せないイベントについては、ステータスのポーリングも続けてください。

## セットアップ

1. VoiceCheapアカウントで[APIページ](https://app.voicecheap.ai/page-api)を開きます。
2. **Webhook**で**署名シークレットを生成**を選びます。`whsec_`で始まるシークレットは一度だけ表示されるため、コピーしてサーバーに保存してください。
3. **エンドポイント URL**に`https`のURLを入力し、**保存**を選びます。

以上です。それ以降に開始するすべてのプロジェクトは、そのエンドポイントにイベントを送信します。

> [!NOTE]
>
> Webhook URL はポート 443 の HTTPS を使用し、公開ネットワークアドレスに名前解決される必要があります。認証情報やフラグメントを含む
> URL、プライベートアドレスや予約済みアドレス、リダイレクトは拒否されます。これはアカウントのエンドポイントとプロジェクトごとの上書き URL
> の両方に適用されます。

アクション API または MCP から `webhooks_get`、`webhooks_update`、`webhooks_delete` を使用できます。`webhooks_create_secret` は REST アクション API のみで使用してください。返された署名シークレットは安全に保存してください。MCP では、このアクションの実行も結果のポーリングもできません。

### リクエストごとにエンドポイントを上書きする

`POST /v1/translate`および`POST /v1/projects`は、オプションの`webhookUrl`フィールドを受け入れます。これは、
そのプロジェクトのアカウントエンドポイントのみを上書きします。ステージングトラフィックを別の場所に送信する場合に便利です。

既存のプロジェクトの送信先は、`POST /v1/projects/{projectId}/dub`で`webhookUrl`を指定して変更することもできます。

```bash theme={null}
curl -X POST "https://api.voicecheap.ai/v1/projects" \
  -H "x-api-key: vc_your-key" \
  -F "file=@interview.mp4" \
  -F "targetLanguage=german" \
  -F "webhookUrl=https://staging.your-server.com/voicecheap/webhooks"
```

署名シークレットは常にアカウントシークレットであり、送信先のみが変更されます。

## イベント

| イベント | 発生条件 |
| - | - |
| `project.created` | プロジェクトが存在し、その文字起こしが保存されています。これがSRTをダウンロードする合図です。 |
| `project.creation.failed` | プロジェクトを作成できませんでした。 |
| `project.translation.completed` | 翻訳が完了し、出力の準備が整いました。 |
| `project.translation.failed` | 翻訳に失敗しました。 |
| `project.lipsync.completed` | リップシンクが完了しました。 |
| `project.lipsync.failed` | リップシンクに失敗しました。 |

> [!NOTE]
>
> 文字起こし専用のイベントはありません。プロジェクト作成の応答は文字起こしの完了前に返ります。`project.created`は文字起こしが保存された後にのみ送信され、その後で[`POST /v1/projects/{projectId}/transcript`](https://api-docs.voicecheap.ai/docs/ja/api-reference/project-transcript)から取得できます。

## ペイロード

すべての配信は、JSONボディを含む`POST`です：

```json theme={null}
{
  "type": "project.created",
  "eventId": "evt_9f2c4b1d8e7a4c3f9b2d1e0a5c6b7d8e",
  "projectId": "7fa7d3a3-4f2b-4c1e-9a6d-2b3c4d5e6f70",
  "workflow": "transcription",
  "status": "success",
  "targetLanguage": "german",
  "error": null,
  "occurredAt": "2026-08-19T09:12:00.000Z"
}
```

| フィールド | タイプ | 説明 |
| - | - | - |
| `type` | string | 上記のイベントのいずれか。 |
| `eventId` | string | イベントごとに一意です。重複排除に使用してください。 |
| `projectId` | string | このイベントが属するプロジェクトです。 |
| `workflow` | 文字列 | `transcription` または `translation`。 |
| `status` | 文字列 | `success` または `failed`。 |
| `targetLanguage` | string | 言語固有のイベントでのみ存在します。 |
| `error` | object \| null | `*.failed` イベントでは、REST API と同じ `{ code, message }` 形状になります。[エラーコード](https://api-docs.voicecheap.ai/docs/ja/api-reference/errors.md) を参照してください。 |
| `occurredAt` | string | ISO 8601 タイムスタンプ。 |

ペイロードは意図的に軽量化されています。コンテンツそのものについてはREST APIを呼び出してください。

## 署名の検証

すべての配信には以下のヘッダーが含まれます：

| ヘッダー | 説明 |
| - | - |
| `X-VoiceCheap-Signature` | `sha256=<hex>` — ペイロードのHMAC-SHA256。署名シークレットをキーとして使用します。 |
| `X-VoiceCheap-Timestamp` | Unix秒。リプレイ攻撃を拒否できるように、署名済み文字列に含まれています。 |
| `X-VoiceCheap-Event-Id` | ボディ内の`eventId`と同じ値。サポートリクエスト時に役立ちます。 |

署名は `<timestamp>.<raw body>` をカバーしているため、配信ごとに異なり、以下の両方を証明します。
リクエストが VoiceCheap から送信されたこと、および転送中に本文が改ざんされていないこと。

```js theme={null}
import crypto from 'crypto';
import express from 'express';

const app = express();

// The raw body is required: parsing and re-serializing changes the bytes and the signature will
// never match. This is the single most common cause of failed verification.
app.post('/voicecheap/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const timestamp = req.header('X-VoiceCheap-Timestamp');
  const signature = req.header('X-VoiceCheap-Signature')?.replace('sha256=', '') ?? '';

  // Reject anything older than five minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.status(400).send('Stale timestamp');
  }

  const expected = crypto.createHmac('sha256', process.env.VOICECHEAP_WEBHOOK_SECRET).update(`${timestamp}.${rawBody}`).digest('hex');

  const isValid = expected.length === signature.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

  if (!isValid) return res.status(401).send('Invalid signature');

  const event = JSON.parse(rawBody);
  // Acknowledge quickly, then process asynchronously.
  res.status(200).send('ok');
  handleEvent(event);
});
```

> [!WARNING]
>
> 配信を信頼する前に署名を検証してください。エンドポイントはパブリックURLであり、署名は 本物の VoiceCheap
> イベントと、そこに到達する他のあらゆるものとを区別するものです。

## 応答

`2xx`ステータスで応答して確認してください。**10秒以内**に回答してください。処理を先に行うのではなく、まず確認の応答を返してから作業を行ってください。
処理を先に行うのではなく、まず確認の応答を返してから作業を行ってください。

2xx以外の応答またはタイムアウトは配信失敗として記録され、現時点では再試行されません。

## シークレットのローテーション

APIページで**Rotate**を選択して、新しいシークレットを生成します。以前のシークレットは
直ちに機能しなくなるため、ローテーション後は速やかに新しいシークレットをサーバーにデプロイしてください。

Webhookを削除すると、エンドポイントとシークレットの両方が削除され、配信が停止します。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.