webhook-template-builder

Webhook テンプレートビルダー

目的

Lytics webhook テンプレートを作成し、反復的に改善します。これは、ユーザープロファイルを任意の外部 webhook 宛先が必要とする本文形式に変換する、サーバーサイドの変換処理です。主なモードは build です。ユーザーが宛先（例：「Qualtrics」）を指定するか、ドキュメントの URL を貼り付けると、このスキルは宛先の API ドキュメントを取得し、必要なペイロード、ヘッダー、認証方式を推測してテンプレートを作成します。その後、/v2/template/{id}/test で反復的にテストし、保存して、すぐに使える webhook ジョブの設計図を出力します。

このスキル自体が認証情報、接続、ジョブを作成することはありません。テンプレートを保存した後、認証情報は connection-manager skill に、ジョブは job-manager skill に引き継ぎます。これは integration-setup skill と同じオーケストレーターの境界です。

次の 2 つの webhook ワークフローに対応しています。

• webhook_triggers（デフォルト）：イベントベース。セグメントへの進入時／退出時に実行されます。
• webhook_enrichment（--workflow=enrichment）：リクエスト／レスポンス方式。プロファイルを送信し、レスポンスをストリームに取り込みます。

環境

認証済みの API アクセスが必要です。認証情報の解決については、../references/auth.md を参照してください。

呼び出し方法

list                                              # GET /v2/template
get <id-or-name>                                  # GET /v2/template/{id}
create <name> --type=js1|jsonnet|handlebars [--desired-format=<json-sample>]   # POST /v2/template (raw body); desired_format required for /test
update <id-or-name>                               # PUT /v2/template/{id}  (PUT, not POST -- API reference is wrong)
delete <id-or-name>                               # DELETE /v2/template/{id}
test <id-or-name> [--profile=<field>=<value> | --synthetic | --json=<file-or-paste>]
build <destination-name | docs-URL> [--workflow=trigger|enrichment]
draft <destination-name | docs-URL>               # alias for build that stops before save

読み取り（list、get）はすぐに実行されます。書き込み（create、update、delete）と build の最後の保存処理では、確認ゲートのパターン（../references/confirmation-gate.md）を使用します。

デフォルトのテンプレート言語

デフォルトでは js1（JavaScript）を使用します。Lytics の js1 ランタイムがエントリーポイントとして期待するのは function template(data) { ... } です（一部の外部ドキュメントに記載されている transformData は、ランタイムに適合しません）。グローバル変数：ly_auth_config と ly_job_config（どちらも JSON 文字列です。防御的に JSON.parse してください。Step 5 を参照）。ヘルパー：署名付きリクエストに使用する hmacSha256(message, key)。

確認せずに言語を切り替えないでください

js1 が非決定的なエラー（例：/test が空の本文で 500 を返す）を返した場合、黙って jsonnet に切り替えないでください。まず原因を調査します。

• テンプレートに desired_format が設定されていることを確認します（Probing Notes を参照。/test で本文が空の 500 が発生する最も一般的な原因です）。
• 関数名が transformData ではなく template であることを確認します。
• 同じアカウントの既存の js1 テンプレートで /test を実行し、プラットフォームの問題でないことを確認します。

失敗についてユーザーに伝え、明示的な承認を得てから jsonnet に切り替えてください。切り替えるとテンプレート全体を書き直すことになるため、ユーザーの同意が必要です。

次の場合は jsonnet を使用します。

• ユーザーが明示的に希望した場合
• 宛先で、event.inSeg、event.segSlug などを多用するため、jsonnet の方が実装しやすいテンプレート機能が必要な場合
• js1 のランタイム問題が確認された後、ユーザーが切り替えを承認した場合

調査に基づく作成フロー（build）

Step 1: 宛先を特定する

ユーザーの入力を解析します。入力形式は次の 3 種類です。

• 名前（「Qualtrics」、「Slack」）
• ドキュメント URL（「https://api.qualtrics.com/...」）
• 自由形式の説明（「ユーザーがセグメント X に入ったときに #alerts に Slack メッセージを投稿する」）

入力が名前だけの場合は、<destination> webhook events API reference を WebSearch で検索し、続行する前に上位の検索結果をユーザーに確認します。

Step 2: 宛先のドキュメントを取得する

WebFetch で宛先の API リファレンスを取得します。次の情報を抽出します。

• HTTP メソッドと URL パターン（パスパラメーターがあれば記録します）
• 必須ヘッダー（認証ヘッダーの形式、Content-Type、署名／HMAC ヘッダーがあればその情報）
• リクエスト本文の形式（完全な JSON の例、ネスト構造、必須フィールドと任意フィールド）
• 認証方式（ヘッダーの API キー、ベアラートークン、HMAC 署名付き本文、OAuth）
• レート制限と再試行しないステータスコード（do_not_retry_for_http_status の設定に使用します）

ドキュメントページがペイウォールで保護されているか、内容が空の場合は、関連するセクションを貼り付けるようユーザーに依頼します。

Step 3: サンプルのプロファイルコンテキストを取得する

実際のスキーマに基づいてフィールド参照を確認します。次のいずれかを使用します。

• 実際のプロファイル：entity-lookup skill を使用（ユーザーが識別フィールドと値を指定）
• 合成プロファイル：schema-discovery skill を使用（GET /v2/schema/user/field からフィクスチャを作成）

これを使って、ドラフトで参照している Lytics のフィールド名が実際に存在することを確認します。

Step 4: 推定されるペイロードとヘッダーを提示する

コードの作成前に、ユーザーが修正できるよう概要を提示します。

Destination: Qualtrics XM Events API
Method: POST
URL pattern: https://{datacenter}.qualtrics.com/eventsubscriptions/{subscription}/events
Headers:
  - X-API-TOKEN: <secret>            -> needs auth provider
  - Content-Type: application/json
Body shape:
  { "events": [ { "type": "...", "user": { "email": "..." }, "data": { ... } } ] }
Auth model: API key in X-API-TOKEN header
Non-retry status codes: 400, 401, 403, 404

ユーザーが指定する必要のある情報（データセンター、サブスクリプション ID、シークレット値など）をすべて提示します。

Step 5: テンプレートを作成する

ランタイムが想定するエントリーポイント function template(data) { ... } を使って js1 のソースを生成します。

// Drafted by webhook-template-builder for <destination> on <YYYY-MM-DD>
function template(data) {
  // Defensive: ly_auth_config / ly_job_config may be undefined globals at runtime
  // (e.g., when /test is called with an empty job_config). Always guard with try/catch.
  var auth = {};
  var job  = {};
  try { if (typeof ly_auth_config === "string" && ly_auth_config) { auth = JSON.parse(ly_auth_config); } } catch (e) {}
  try { if (typeof ly_job_config  === "string" && ly_job_config)  { job  = JSON.parse(ly_job_config);  } } catch (e) {}

  return {
    events: [
      {
        type: "user_segment_enter",
        user: { email: data.email || "" },
        data: {
          first_name: data.first_name || "",
          last_name:  data.last_name  || "",
          ltv:        data.ltv        || 0
        }
      }
    ]
  };
}

規約：

• 関数名は transformData ではなく template です。 エントリーポイントがない場合、Lytics の js1 ランタイムは空の本文で 500 を返します。プラットフォーム上の既存の js1 テンプレートでは、一貫して template(data) が使われています。
• Step 3 で存在を確認したフィールドには、data.<field> 参照を使います。
• デフォルト値：文字列には || ""、数値には || 0、配列には || [] を使います。Webhook の宛先では、null が許容されないことがほとんどです。
• ly_auth_config と ly_job_config は、必ず typeof === "string" チェックと try/catch で保護してください。 リクエストで対応するキーが空または欠落している場合、/test エンドポイントはこれらのグローバル変数を渡しません。保護なしで JSON.parse(ly_job_config || "{}") を実行すると、実行時に ReferenceError が発生します。
• 宛先でリクエストへの署名が必要な場合は hmacSha256(message, key) を使います。
• 追跡可能性を確保するため、ヘッダーコメント行を追加します。

ソースをユーザーに提示します。フィードバックを受けてメモリ上で修正し、まだ API には書き込みません。

Step 6: /test のループ

/test エンドポイントには既存のテンプレート ID が必要なため、まずドラフトを保存します。list で見つけやすいよう、ドラフト名は _draft_<unix-ts>_<destination-slug> の形式にします。作成時には desired_format を設定する必要があります。 設定しない場合、/test は空の本文で 500 を返します。Step 4 で推定したレスポンスの形（宛先が期待するサンプル）を使用します。フォールバックとして、最小限の {} でも構いません。

DRAFT_NAME="_draft_$(date +%s)_qualtrics"
# desired_format is a JSON sample of the destination payload; URL-encode it.
DESIRED_FORMAT=$(printf '%s' '{"firstName":"","lastName":"","email":"","embeddedData":{}}' \
  | python3 -c "import sys,urllib.parse; print(urllib.parse.quote(sys.stdin.read()))")

# Save the draft
curl -s -X POST \
  "${LYTICS_API_URL:-https://api.lytics.io}/v2/template?name=${DRAFT_NAME}&type=js1&description=Draft%20for%20${DESTINATION}&desired_format=${DESIRED_FORMAT}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  --data-binary @template.js

返された template_id を記録します。その後、テストします（下記の「テストワークフロー」を参照）。フィードバックに基づいて PUT /v2/template/{id} で更新し、再テストします。出力が意図どおりにレンダリングされるまで繰り返します。

_draft_* テンプレートは Lytics の UI リストに表示される場合があり、Step 7 で名前を変更することをユーザーに伝えます。

Step 7: 保存（名前の変更）

テストに合格したら、最終的な名前と説明を確認してから、update を実行してドラフトの名前を変更します。書き込む前に、確認ゲート（../references/confirmation-gate.md）を通して完全なペイロードを提示します。

Step 8: ジョブのブループリントを出力して引き継ぐ

Webhook ジョブ設定のペイロード全体を出力します（下記の「Webhook ジョブ引き継ぎブループリント」を参照）。次の内容を含めます。

• template_id に値を設定
• 推定値（Step 4 の headers、レート制限のドキュメントに基づく do_not_retry_for_http_status）
• 残りの項目にはプレースホルダーを指定（auth_ids: ["<TODO via connection-manager>"]、audiences: ["<segment_id>"]）

続けて、次のように明示的に引き継ぎます。

「テンプレートは <final_name>（<template_id>）として保存されました。ジョブを接続するには：

1. connection-manager skill を実行して、宛先用の header_param_auth プロバイダーを作成します。webhook_request_headers に key: value の行（1 行につき 1 つ）を入力し、宛先に必要な情報（X-API-TOKEN、Content-Type など）をすべて指定します。返された auth_id を記録します。
2. 下記の設定で job-manager skill を実行し、auth_ids[] に auth_id を設定します。Lytics はジョブの実行時に、認証のヘッダーをすべての送信リクエストに自動で挿入します。ジョブ設定自体には headers フィールドはありません。」

テストワークフロー

モード	フラグ	ソース
実在するプロフィール	--profile=<field>=<value>	entity-lookup skill（GET /api/entity/user/<field>/<value>）を組み合わせます。返されたプロフィールを entity として使用します
合成フィクスチャ	--synthetic	schema-discovery skill（GET /v2/schema/user/field）を組み合わせます。タイプごとにフィクスチャを作成します
ユーザー指定の JSON	--json=<file-or-paste>	リテラルな JSON エンティティ blob を受け取り、解析できることを検証します

テストリクエストの本文は {job_config, entity} です。最終的な webhook ジョブ設定の簡略版（audience_trigger_events、webhook_url、ヘッダーなど）から job_config を合成し、テンプレートが本番環境で受け取る実際の設定で実行されるようにします。レンダリング出力は文字列であり、その文字列が宛先に POST される本文です。

合成フィクスチャのデフォルト値

GET /v2/schema/user/field から返される各タイプに対して、妥当な値を設定します。

フィールドのタイプ	デフォルト値
string	"sample_value"。識別情報に関するフィールドには、実際にありそうな代替値を使用します（email → "[email protected]"、phone → "+15555550100"）。
int / number	1
bool	false
[]string	["sample"]
date / ts	現在の ISO-8601 タイムスタンプ
_segments	["test_segment"]
_id、_uid	"sample-id"

API エンドポイント

テンプレートの一覧表示

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/template" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

一覧のレスポンスに含まれるのはメタデータのみで、ソース本文は含まれません。本文はどの GET エンドポイントからも取得できません（調査メモを参照）。取得できるのは name、type、description、desired_format、タイムスタンプのみです。

テンプレートの取得

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/template/${TEMPLATE_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

メタデータのみを返します（id、name、type、description、target、field_filter、desired_format、created、updated、author_id）。ソース本文はいずれの GET パスからも取得できません。調査メモを参照してください。ユーザーがソースレベルの履歴を必要としている場合は、テンプレート本文を独自のバージョン管理に保管することを推奨してください。

テンプレートの作成

curl -s -X POST \
  "${LYTICS_API_URL:-https://api.lytics.io}/v2/template?name=${NAME}&type=${TYPE}&description=${DESCRIPTION}&desired_format=${DESIRED_FORMAT}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  --data-binary @template.js

• メタデータ（name、type、description、任意の account_id、desired_format）はクエリー文字列に指定します。
• テンプレートソースは本文にプレーンテキストとして指定します。
• type の列挙値：js1、jsonnet、handlebars。Lytics API リファレンスページには js1 が記載されていませんが、本番環境ではサポートされています。API に拒否された場合（400 invalid type）は、調査メモを参照してください。
• **/test を成功させるには desired_format が必須です。**これは宛先が期待するペイロードのサンプル（JSON 文字列。URL エンコードしてください）です。空の場合、/test は本文が空の 500 を返します。宛先のドキュメントから本文の形状を推測して使用してください（ステップ 4）。ほかに適切な値がない場合は、プレースホルダーとして最小限の {} を使用できます。

テンプレートの更新

curl -s -X PUT \
  "${LYTICS_API_URL:-https://api.lytics.io}/v2/template/${TEMPLATE_ID}?name=${NAME}&type=${TYPE}&description=${DESCRIPTION}&desired_format=${DESIRED_FORMAT}" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  --data-binary @template.js

**更新には POST ではなく PUT /v2/template/{id} を使用します。**Lytics API リファレンスページでは誤って POST と記載されています。このルートに対する本番 API の POST は 405 Method Not Allowed と Allow: GET, OPTIONS, DELETE, PUT, HEAD を返します。リファクタリングでこれを POST に「修正」しないでください。

テンプレートの削除

curl -s -X DELETE "${LYTICS_API_URL:-https://api.lytics.io}/v2/template/${TEMPLATE_ID}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

テンプレートのテスト

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/template/${TEMPLATE_ID}/test" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "job_config": {
      "audience_trigger_events": "enter",
      "webhook_url": "https://example.com/webhook"
    },
    "entity": {
      "email": "[email protected]",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "_segments": ["high_value_customers"]
    }
  }'

レスポンス：{data: "<rendered string>", status: 200, request_id: "..."}。レンダリングされた文字列が、宛先に POST される本文です。

テストエンドポイントで知っておくべき注意点：

• リクエスト本文に job_config がまったく含まれていない場合、または job_config が {} の場合、ランタイムは ly_job_config をグローバルとして渡しません。そのため、ガードなしの JSON.parse(ly_job_config || "{}") は ReferenceError: ly_job_config is not defined をスローします。必ず try { if (typeof ly_job_config === "string" && ly_job_config) { ... } } catch (e) {} でガードしてください（ステップ 5 のスキャフォールドではこの処理を行います）。
• ランタイムエラーは {data: "<error message>", status: 200} で返されます。テンプレートが例外をスローした場合も HTTP 200 です。data に "evaluating snippet: RUNTIME ERROR"（jsonnet）というプレフィックス、または JS の例外トレースが含まれているか確認してください。
• /test が本文の空の HTTP 500 を返す場合、最も一般的な原因はテンプレートで desired_format が未設定であることです。PUT で設定してから再試行してください。

調査メモ

テンプレート API の詳細の一部は、公開リファレンスドキュメントと稼働中のランタイムで異なっています。以下の調査結果は api.lytics.io で確認済みです。これらを事実として扱い、ドキュメントだけを根拠に並べ替えたり「修正」したりしないでください。

不明点	解決内容
js1 のエントリーポイント関数名	function template(data) { ... }（transformData ではありません）。エントリーポイントがない場合、ランタイムは空の本文とともに 500 を返します。プラットフォーム上の既存の js1 テンプレートでは、一貫して template が使われています。
/test で desired_format が必須か	必須です。 指定しない場合、/test はエラーメッセージなしで空の本文とともに 500 を返します。作成時、または PUT による更新で設定してください。この値は、宛先が期待するペイロードの JSON サンプルです（クエリパラメーターとして URL エンコードしてください）。フォールバックとして最小限の {} を使用できます。
更新時の HTTP メソッド	PUT /v2/template/{id}（POST ではありません）。API リファレンスには POST と記載されていますが、稼働中のエンドポイントは Allow: GET, OPTIONS, DELETE, PUT, HEAD とともに 405 Method Not Allowed を返します。
/test における空の job_config	テスト本文で job_config が {} または未指定の場合、ランタイムは ly_job_config をグローバル変数として渡しません。テンプレートでは try { if (typeof ly_job_config === "string" && ly_job_config) { ... } } catch (e) {} のようにガードしてください。ly_auth_config にも同じことが当てはまります。
作成本文の Content-Type	js1 と jsonnet のどちらも、生の本文で text/plain が機能します。実際には 415 のフォールバックは不要です。発生した場合は、application/javascript または application/jsonnet を試してください。
type=js1 は受け付けられるか	はい。 API リファレンスの列挙型にはありませんが、受け付けられます。jsonnet と handlebars も受け付けられます。
GET レスポンスのソース本文	取得できません。 ?include_body=true、?show_body=true、?fields=body、/v2/template/{id}/source、/body、/code、/raw を試しましたが、いずれもメタデータのみを返すか、405 を返します。テンプレートは作成後に書き込み専用となるため、履歴を残したい場合はソースをユーザー自身のバージョン管理下に保存してください。
hmacSha256 と hmacSHA256	デフォルトは hmacSha256（例で最もよく使われています）。既存のテンプレートを読み取る際は、どちらでも受け付けてください。
Webhook ジョブの設定フィールド名と列挙値	公開ドキュメントと以前のブループリントの例は、稼働中の API と異なっています。GET /v2/provider では、この API の範囲におけるワークフローの config_routes は公開されません。最も確実な確認方法は、既存の Webhook ジョブを一覧表示し（GET /v2/job?show_all=true、workflow ~= /webhook/ でフィルタリング）、その config の形状を確認することです。2026-04-27 時点で稼働中の名前は、webhook_triggers / webhook_enrichment（ワークフローのスラッグ）、segment_ids（audiences ではありません）、列挙値が "" / enters_only / exits_only の audience_events（enter / exit の audience_trigger_events ではありません）、array[int] の do_not_retry（CSV 文字列ではありません）、withbackfill（existing_users ではありません）です。headers フィールドはありません。ヘッダーは auth_ids[] を介して認証プロバイダーから取得します。

Webhook ジョブ引き継ぎブループリント

タグキーの規約：ユーザーに確認、ドキュメントから推測、スキルの出力から取得、解決（Lytics を調査）。

認証とヘッダーの引き渡し方法

Webhook ジョブの設定には headers フィールドがありません。ヘッダー（X-API-TOKEN、Authorization など）と URL クエリパラメーターは、ジョブではなく認証プロバイダーに設定します。実行時に Lytics は auth_ids[] の参照からこれらを抽出し、送信リクエストに自動的にマージします。

connection-manager skill に引き継ぐ際は、ユーザーに header_param_auth タイプの認証プロバイダーを作成し、次の項目を設定するよう伝えてください。

• webhook_request_headers -- 改行区切りの key: value 形式のテキストです。Qualtrics の例：

  X-API-TOKEN: <secret>
  Content-Type: application/json
  

• webhook_request_params -- 送信先でクエリパラメーター認証が必要な場合の URL クエリ文字列形式（key=value&key2=value2）です。

OAuth（oauth2_client_credentials 認証タイプ）の場合、Lytics は Authorization: Bearer <token> を自動挿入します。カスタマイズするには、認証設定の webhook_request_headers 内にリテラルの {token} プレースホルダー（波括弧は1組で、{{token}} ではありません）を入れます。例：Authorization: Token token={token}。Lytics はリクエスト時にサーバー側で置き換えます。

テンプレートは、テンプレート本文内で ly_auth_config（認証設定全体の JSON エンコードされた設定データ）を読み取ることもできます。これは HMAC 署名や、本文側での認証情報の使用を目的としたもので、ヘッダーの挿入とは別のものです。

出力前にワークフロー設定スキーマを確認する

2026-04-27 時点で確認済みのスラッグは webhook_triggers と webhook_enrichment で、フィールドの形式は以下のブループリントに示されています。GET /v2/provider は webhook プロバイダーを返しますが、この API サーフェスではそのワークフローの config_routes を公開しません。そのため、機械可読なスキーマを取得できる適切なエンドポイントはありません。代わりに、ブループリントを出力する前に、送信先アカウントに既存の webhook ジョブがあるか確認してください。

# List webhook jobs and inspect their config shape
curl -s "${LYTICS_API_URL}/v2/job?show_all=true" -H "Authorization: ${LYTICS_API_TOKEN}" \
  | jq '.data[] | select(.workflow | test("webhook"; "i")) | {id, name, workflow, config}'

webhook ジョブが1つ以上ある場合、その config キーを正としてください。存在しない場合は、以下のブループリントを使用してください。これらは、実際に稼働している webhook_triggers ジョブと、lytics/lio の基盤となるワークフロー定義（data/workflow/webhook_v2.json、data/workflow/webhook_enrichment.json、および src/api/v2/models/job_configs.go の WebhookTriggers／WebhookEnrichment Go 構造体）に照らして確認済みです。フィールド名は過去に公開ドキュメントから変更されているため（例：実際の API では audience_trigger_events ではなく audience_events、audiences ではなく segment_ids を使用し、do_not_retry は CSV 文字列ではなく array[int] で、headers フィールドはありません）、判断に迷う場合はドキュメントより既存の実ジョブを優先してください。

オーディエンストリガー（--workflow=trigger、デフォルト）

webhook_triggers ワークフローに対応します。確認済みの形式：

{
  "name":        "<ASK USER -- defaults to '<destination> trigger for <segment>'>",
  "description": "<INFER>",
  "workflow":    "webhook_triggers",
  "auth_ids":    ["<FROM connection-manager hand-off -- the auth provider holds the credential headers>"],
  "config": {
    "segment_ids":         ["<ASK USER -- segment hex id(s) (NOT slugs)>"],
    "webhook_url":         "<INFER FROM DOCS or ASK USER -- must be HTTPS>",
    "http_method":         "POST",                                  // enum: GET|POST|PUT|PATCH|DELETE
    "audience_events":     "",                                      // enum: "" (both, default), "enters_only", "exits_only"
    "template_id":         "<FROM SKILL OUTPUT -- omit for raw default Lytics payload>",
    "user_fields":         null,                                    // optional: subset of profile fields to export; null = all
    "field_changes":       [],                                      // optional: up to 75 field names whose changes also trigger
    "withbackfill":        false,                                   // include users already in audience
    "include_segs":        false,                                   // include profile's segment membership as `segments_all`
    "batch_requests":      false,
    "batch_size":          10,                                      // max 1000
    "batch_flush_duration": 5,                                      // seconds, max 300
    "worker_count":        5,                                       // max 20
    "do_not_retry":        [400, 401, 403, 404],                    // array[int] -- HTTP statuses to NOT retry
    "cloudevents":         false,                                   // wrap payload in CloudEvents v1.0 envelope
    "cloudevents_type":    null,                                    // default: com.lytics.audience.user.event
    "cloudevents_source":  null                                     // default: /work/id
  }
}

ユーザーエンリッチメント（--workflow=enrichment）

webhook_enrichment ワークフローに対応します。確認済みの形式：

{
  "name":        "<ASK USER>",
  "description": "<INFER>",
  "workflow":    "webhook_enrichment",
  "auth_ids":    ["<FROM connection-manager hand-off>"],
  "config": {
    "segment_ids":     ["<ASK USER -- segment hex id(s)>"],
    "stream":          "webhook_enrichment",                        // optional; lands the response in stream of this name
    "webhook_url":     "<INFER FROM DOCS or ASK USER -- must be HTTPS>",
    "http_method":     "POST",                                      // enum: GET|POST|PUT|PATCH (no DELETE for enrichment)
    "template_id":     "<FROM SKILL OUTPUT>",
    "user_fields":     null,                                        // optional: subset of profile fields to send
    "field_changes":   [],                                          // optional: trigger on field changes (up to 75)
    "withbackfill":    true,                                        // NOTE: defaults to true for enrichment (false for triggers)
    "audience_events": "",                                          // enum: "" (both) | "enters_only" | "exits_only"
    "worker_count":    5,                                           // max 20
    "do_not_retry":    [400, 401, 403, 404]                         // array[int]
  }
}

スキルが推測できなかったフィールドには 「要注意」 と注記し、job-manager が書き込む前にユーザーが確認できるようにしてください。注： どちらのワークフロー設定にも headers フィールドはありません。認証情報は auth_ids[] を介して渡されます。上記の「認証とヘッダーの引き渡し方法」を参照してください。

動作

読み取り操作（list、get）

直ちに実行します。テンプレートを表形式で表示し、ID、名前、タイプ、説明、更新日時を示します。

書き込み操作（create、update、delete、build の保存ステップ）

確認ゲートのパターンを使用します。ペイロード全体（未加工のソースとクエリパラメーターのメタデータ）および解決済みの curl 呼び出しを表示し、書き込む前に明示的な yes を求めます。

test の場合

保存済みのテンプレートに対するテストでは、送信先に対する読み取り専用操作のため、確認は不要です。レスポンスをインラインで表示します。build 中に作成したドラフトに対してテストを実行した場合は、そのドラフト自体がすでに作成時の確認ゲートを通過したものとして扱います。

エラー処理

• テンプレートで404が返る場合 -- list に対してあいまい検索を提示します（name の部分一致、大文字と小文字は区別しません）。
• POST /v2/template/{id} で405が返る場合 -- 更新に使うメソッドは POST ではなく PUT です。PUT で再試行します。
• /test で本文が空の500が返る場合 -- ほとんどの場合、テンプレートに desired_format が設定されていないか、js1 のエントリーポイント名が template 以外になっています。GET /v2/template/{id} で両方を確認します。desired_format が設定されていない場合は PUT で設定し、ソース内の関数名が template(data) でない場合は変更します。
• HTTP 200 で data: "ReferenceError: ly_job_config is not defined" が返る場合 -- テンプレートでガードされていない JSON.parse(ly_job_config) が実行されています。try { if (typeof ly_job_config === "string" && ly_job_config) { ... } } catch (e) {} で囲み、再テストします。
• HTTP 200 で data: "ReferenceError: <field>"（jsonnet）または JS の例外トレース（js1）が返る場合 -- 参照先のエンティティフィールドがありません。デフォルトのフォールバックを追加するか、Step 3 のスキーマ検出で適切なフィールド名を選びます。
• type=js1 での作成時に400が返る場合 -- このアカウントでは API がその列挙値を受け付けない可能性があります。ユーザーに明確なエラーを提示し、jsonnet に黙って切り替えないでください（Default Template Language セクション）。
• 作成時／更新時に415が返る場合 -- Content-Type のプローブに失敗しました。別の値（js1 の場合は application/javascript、jsonnet の場合は application/jsonnet）で再試行します。セッション中は動作した値をキャッシュします。
• 宛先から HMAC の不一致が報告された場合 -- ly_auth_config 内のシークレットが宛先の期待値と異なるか、hmacSha256 に渡す入力の順序またはエンコードが間違っています。宛先のエラーをそのままユーザーに提示します。
• WebFetch で有用なコンテンツが返らない場合（ペイウォール、レート制限、JS によるレンダリング）-- 関連するドキュメントのセクションを貼り付けるようユーザーに依頼します。
• 実際のジョブで宛先から401が返る場合 -- このスキルでは動作するテンプレートを保存済みです。問題は認証にあります。ユーザーを connection-manager skill に案内します。

依存関係

• 構成要素：entity-lookup skill、schema-discovery skill、connection-manager skill、job-manager skill
• 使用するファイル：../references/auth.md、../references/api-client.md、../references/confirmation-gate.md、../references/api-response-format.md
• 関連項目：integration-setup skill（オーケストレーターへの引き継ぎパターン）、integration-advisor skill（調査主導型アドバイザーのパターン）