Skip to main content
Webhooks

Webhook Endpoint を作成する

Webhook の受信 URL と購読するイベントを登録します。

Webhook は現在 Beta 機能です。API、フィールド、および動作は今後のバージョンで変更される可能性があります。
POST /api/v1/forward/webhook/endpoints

リクエストヘッダー

Header必須説明
AuthorizationはいBearer <PAT または管理者 SAT>
Content-Typeはいapplication/json
Idempotency-Keyいいえ任意の冪等性キー。同じキーは同一リクエストにのみ再利用してください。

リクエストボディのパラメーター

フィールド必須説明
urlstringはいイベントを受信する HTTP または HTTPS URL。本番環境では HTTPS を推奨します。
descriptionstringいいえEndpoint の用途。
eventsstring[]はい購読イベント。1 件以上必要です。* または namespace.name 形式の具体的なイベント名を指定できます。forward.* などの前方一致ワイルドカードはサポートされません。完全なイベント名とトリガーはサポート対象の公開イベントを参照してください。このカタログにあるイベントのみ Forward の配信契約の対象です。
metadataobjectいいえカスタム文字列のキーと値。

リクエスト例

curl -s -X POST 'https://api.qoder.com/api/v1/forward/webhook/endpoints' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: webhook-endpoint-production' \
  -d '{
    "url": "https://example.com/webhooks/qoder",
    "description": "Schedule notifications",
    "events": [
      "forward.schedule.created",
      "forward.schedule_run.succeeded",
      "forward.schedule_run.failed"
    ],
    "metadata": {
      "environment": "production"
    }
  }'

レスポンス例

HTTP 201 Created
{
  "id": "e149c233-1234-4abc-8def-1234567890ab",
  "url": "https://example.com/webhooks/qoder",
  "description": "Schedule notifications",
  "events": [
    "forward.schedule.created",
    "forward.schedule_run.succeeded",
    "forward.schedule_run.failed"
  ],
  "metadata": {
    "environment": "production"
  },
  "active": true,
  "signing_secret": "whsec_BASE64_ENCODED_SECRET",
  "created_at": "2026-09-01T08:00:00Z"
}

レスポンスフィールド

フィールド説明
idstringEndpoint ID。不透明な文字列として保存してください。
urlstringイベント受信 URL。
descriptionstringEndpoint の説明。
eventsstring[]現在の購読イベント。
metadataobjectカスタムメタデータ。レスポンスにはプラットフォームが管理するフィールドが含まれる場合があります。
activebooleanEndpoint が有効かどうか。新規作成時は true です。
signing_secretstringWebhook 署名を検証するためのシークレット。このレスポンスでのみ返されます。
created_atstring作成日時。RFC 3339 形式。
signing_secret はレスポンス受信後すぐに安全に保存してください。一覧、取得、更新 API では再表示されません。

エラー

HTTPType発生条件
400invalid_request_errorURL、イベント一覧、メタデータ、またはリクエストボディが不正です。
401authentication_error認証情報がない、無効、または期限切れです。
403permission_error現在のトークンでは Webhook を管理できません。
409conflict_error冪等性キーが既存リクエストと競合しているか、Endpoint 数が上限に達しています。
413invalid_request_errorリクエストボディが大きすぎます。
429rate_limit_errorリクエスト頻度が制限に達しています。

関連