# Webhooks

Webhooks を使用して、ポーリングせずにタスクおよび請求イベントを受信します。 Tripo は、サブスクライブされたイベントが発生すると、JSON ペイロードを HTTPS エンドポイントに送信します。

## セットアップ

1. 「設定」を開き、「Webhooks」を開きます。
2. HTTPS エンドポイント (`https://api.yourapp.com/tripo-webhook` など) を追加します。
3. 受信したいイベントの種類を選択します。
4. エンドポイントを保存します。
5. 署名シークレットをコピーして安全に保管します。 1回のみ表示されます。

## イベントの種類

| イベント | 説明 |
| --- | --- |
| `task.completed` | タスクが正常に終了しました。 |
| `task.failed` | タスクが失敗したか、キャンセルされました。 |
| `balance.low` | アカウント残高が設定されたクレジット アラートしきい値を下回りました。 |

## リクエストヘッダー

| ヘッダー | 説明 |
| --- | --- |
| `Tripo-Webhook-Id` | Webhook エンドポイント ID。 |
| `Tripo-Webhook-Delivery` | ユニークな配信ID。冪等性のために使用します。 |
| `Tripo-Webhook-Event` | イベント タイプ (`task.completed` など)。 |
| `Tripo-Webhook-Signature` | `{timestamp}.{raw_body}` に対する HMAC-SHA256 署名。 |
| `Content-Type` | 常に `application/json`。 |

## 検証

1. `Tripo-Webhook-Signature` から `t` と `v1` を解析します。
2. `t + "." + rawBody` を介して署名シークレットを使用して HMAC-SHA256 を計算します。
3. 定数時間比較を使用して、計算された 16 進ダイジェストを `v1` と比較します。
4. 必要に応じて、約 5 分より古いタイムスタンプを拒否します。

## ベストプラクティス

- `2xx` 応答をすぐに返し、負荷の高い作業を非同期で処理します。
- アプリケーションの状態を変更する前に、すべてのペイロードを確認してください。
- `Tripo-Webhook-Delivery` を使用してイベントの重複を排除します。
- `balance.low` を使用して、クレジット不足のためにタスクの作成が失敗する前にユーザーに警告します。