Webフック
Webhook URL を設定すると、ファイル翻訳ジョブ(/jobs)が終了した際に(成功した場合でも失敗した場合でも)、サーバーに通知されます。POST /jobs/{id}/cancel でキャンセルされたジョブにはコールバックは送信されません。ドキュメント操作およびメディアジョブについては、それぞれのクエリエンドポイントをポーリングしてください。
Webhookを管理する
Section titled “Webhookを管理する”API経由で管理可能、ユーザーあたり最大3つ:
POST /api/v1/webhooks createGET /api/v1/webhooks listPATCH /api/v1/webhooks/{id} update / disableDELETE /api/v1/webhooks/{id} delete例を作成する:
curl -X POST https://omnidoc.top/api/v1/webhooks \ -H "X-API-Key: sk_your_key" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-server.com/hooks/omnidoc", "secret": "your-signing-secret", "events": ["job.completed"], "description": "Production callback" }'URLはパブリックインターネットから到達可能でなければならず、できれば HTTPS 経由である必要があります。プライベートネットワーク、ローカルアドレス、および形式不正な URL は 400 を返します。PATCH リクエストでは、url、secret、events、description、および status を変更できます(active / disabled)。
コールバック形式
Section titled “コールバック形式”POST your-webhook-urlContent-Type: application/jsonX-Webhook-Event: job.completedX-Webhook-Timestamp: 1782900150X-Webhook-Signature: sha256=...{ "event": "job.completed", "timestamp": 1782900150, "data": { "job_id": "q3f8s6c2a9m1k4tx", "status": "completed", "file_name": "report.docx", "char_count": 12840 }}| イベント | いつ |
|---|---|
job.completed | ジョブが終了する;data.status は completed または failed である |
失敗したジョブにも job.completed イベントが使用されます。data.status == "failed" およびオプションの data.error で区別してください。成功したジョブには error フィールドはありません。data.char_count は翻訳文字数を示し、失敗したジョブでは 0 が使用されます。
events は job.completed および *(すべてのイベント)のみを受け付けます。他の値または空のリストを指定すると、422 エラーが返されます。PATCH リクエストでは、変更しないフィールドは省略してください。null を送信した場合も、422 エラーが返されます。
署名を検証する
Section titled “署名を検証する”Webhookにsecretを設定すると、すべてのコールバックにX-Webhook-Signatureが付与されます。生のリクエストボディ上でHMAC-SHA256を使ってこれを確認してください:
import hashlibimport hmacimport jsonimport time
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode(), payload, hashlib.sha256 ).hexdigest() return hmac.compare_digest(f"sha256={expected}", signature)
def parse_webhook(payload: bytes, signature: str, secret: str, tolerance: int = 12 * 3600) -> dict: if not verify_webhook(payload, signature, secret): raise ValueError("invalid signature") event = json.loads(payload) if abs(time.time() - event["timestamp"]) > tolerance: raise ValueError("stale event") return event署名は本文のみを対象とし、ヘッダーは対象外です。リプレイ攻撃防止のため、署名が検証に合格した後、本文内で timestamp を確認します(X-Webhook-Timestamp と同じ値ですが、署名対象は本文の値のみです)。また、data.job_id および data.status により重複排除を行います。再試行では、最初の配信時の本文を変更せずにそのまま再送信し、timestamp の値も同一にします。最後の再試行は最初の配信から約8.6時間後に実施されるため、その期間よりも短くウィンドウを設定しないでください(例では12時間を使用しています)。
- 受信側は、配信を成功とみなすために15秒以内に
2xxを返信しなければなりません。リダイレクトは追跡されません。 - 配信失敗(タイムアウト、接続エラー、または非
2xx)は自動的に再試行されます。前回の失敗から1分後、5分後、30分後、2時間後、6時間後にそれぞれ再試行され、各イベントにつき最大6回まで試みた後は、それ以上は実施されません。 - 再試行は、本文を変更せずにWebhookの現在のURLに送信されます(
timestamp、dataおよび署名は最初の配信と一致します。間にsecretが変更された場合は、新しいsecretで署名されます)。既に配信済みのイベントは再度送信されません。 - Webhookが無効化、削除された場合、またはイベントのサブスクリプションが解除された場合、保留中の再試行はキャンセルされます。
- レシーバーは、
data.job_idおよびdata.statusに基づいてイベントを冪等的に処理し、安全に永続化した後、迅速に応答する必要があります。 - 1つのアカウントに設定された複数のWebhookは並列で配信されます。受信処理が遅い場合でも、他のWebhookの配信が妨げられることはありません。
- 10回連続で配信に失敗した場合(再試行を含む)、Webhookは自動的に無効化されます。受信側の問題が解決次第、
PATCHを使用して再度有効にしてください。 GET /api/v1/webhooksには、各Webhookの最終トリガー時刻、ステータスコード、および連続失敗回数が表示されます。