API docs by Redocly

Jolt External API (1.0.0)

Download OpenAPI specification:

Jolt の外部 API。

認証スキーマ

エンドポイントごとに異なります。

グループ 認証方式 ヘッダ / フィールド
Referral / ReferralTransaction / ReferralCustomFieldValue / ReferralActivityLog API キー X-Jolt-API-Key
Tag パブリックトークン (リクエストボディ内) program_token: "pub_..."
StripeWebhook Stripe 署名 Stripe-Signature (Stripe Dashboard で設定する Webhook の署名シークレットで検証)

Referral

リード関連の操作

Lead ステータス更新

Referral Lead のステータスを更新する。 Lead の特定には organization_id / lead_id / referral_id / custom_field_id + custom_field_value のいずれか1つを指定する。 Vendor / VendorProgram の整合性が取れない場合は 404 を返す。

計測タグは won を送れない（POST /api/tracking/lead-status が 400 で拒否する）ため、 有料転換の連携はこのエンドポイントで行う。その際は計測タグで送ったのと同じ organization_id を指定すれば、Jolt 内部の ID を調べる必要がない。

Authorizations:
apiKeyAuth
header Parameters
X-Dry-Run
string
Value: "true"
Example: true

true を指定すると、認証およびリクエストバリデーションのみ実行し、 DB操作をスキップして 200 OK を返す。疎通確認用。

Request Body schema: application/json
required
organization_id
string non-empty

計測タグ (POST /api/tracking/lead-status) で送ったのと同じ組織 ID。 system-managed カスタムフィールド「組織ID」で突合する。 custom_field_id と違い Jolt 内部の ID を知る必要がないため、 有料転換時に won へ更新する用途ではこちらを使うのが簡単。 同じ値の紹介がプログラム内に複数ある場合は最新の紹介を対象にする（タグ経路と同じ挙動）。

lead_id
string

Referral Lead ID（Jolt 内部 ID）

referral_id
string

Referral ID（Jolt 内部 ID）。紐付く Referral Lead を特定する。

custom_field_id
string

カスタムフィールド ID（ULID）

custom_field_value
string

カスタムフィールドの値

status
required
string
Enum: "qualified" "unqualified" "won" "lost"

Lead ステータス。 qualified: 適格 unqualified: 不適格 won: 取引成立 lost: 取引不成立

status_detail
string or null

ステータス詳細。 unqualified / lost の場合のみ指定可能。

Responses

Request samples

Content type
application/json
Example
{
  • "lead_id": "01KB1S3TSZ4KMW6TR84KF6KPXC",
  • "status": "qualified"
}

Response samples

Content type
application/json
Example
{ }

Lead 作成（紹介コード）

紹介コード付きの申込データから Referral Lead を作成する。 計測タグを置けない構成（申込フォームが別ドメイン / iframe、自社システムで申込を受けている等）で、 紹介の紐づけを行うための経路。

紹介コードは必須。紹介元を特定できないリードは作成しない。 コードはプログラム単位で照合するため、他プログラムのコードは受け付けない。 対象プログラムが「紹介コード方式」に設定されている必要がある（リンク方式では 400 を返す）。

作成されるリードのリードソースは、コードから特定した紹介元に応じて partner_code（パートナーの紹介コード） / referrer_code（リファラーの紹介コード）になる。 既存のリンク経由と同様に lead.created Webhook・通知メールが発火する。

冪等性: external_source_id を指定すると、同一プログラム内で同じ値の申込が再送されても リードは重複作成されず 200 {} を返す（Webhook・通知メールも再発火しない）。 API のリトライで重複リードを作らないため、外部システム側の申込IDを渡すことを推奨する。

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
vendor_program_id
required
string

VendorProgram ID。API キーに紐づくプログラムと一致している必要がある。

referral_code
required
string

紹介コード（8桁の英数字）。必須。 大文字小文字・全角半角は吸収して照合するため、フォームの入力値をそのまま渡してよい。

customer_name
string

紹介先の会社名

customer_contact_last_name
string

紹介先の担当者の姓

customer_contact_first_name
string

紹介先の担当者の名

customer_contact_email
string

紹介先の連絡先メールアドレス

note
string

備考

external_source
string

外部システムの識別子（任意）。冪等性キー external_source_id に付随する情報として保存する。 例: 自社CRMを表す "crm" など。

external_source_id
string

冪等性キー（任意）。外部システム側の申込ID等を渡す。 同一プログラム内で同じ値の申込が再送された場合、リードは重複作成されず 200 {} を返す（冪等）。 未指定の場合は冪等性判定を行わず、毎回新規リードを作成する。

Responses

Request samples

Content type
application/json
Example
{
  • "vendor_program_id": "01KB1S3TSZ4KMW6TR84KF6KPXC",
  • "referral_code": "ABCD2345",
  • "customer_name": "株式会社サンプル",
  • "customer_contact_last_name": "山田",
  • "customer_contact_first_name": "太郎",
  • "customer_contact_email": "taro.yamada@example.com",
  • "note": "資料請求フォームより"
}

Response samples

Content type
application/json
{ }

ReferralTransaction

取引レコードの操作

取引レコード作成

紹介された顧客に対する取引レコードを作成する。 顧客の特定には organization_id / customer_id / referral_id / custom_field_id + custom_field_value のいずれか1つを指定する。 計測タグを使っている場合は、タグで送ったのと同じ organization_id を指定すれば Jolt 内部の ID を調べる必要がない。 作成後、顧客向け報酬作成メッセージを非同期で送信する。

Authorizations:
apiKeyAuth
header Parameters
X-Dry-Run
string
Value: "true"
Example: true

true を指定すると、認証およびリクエストバリデーションのみ実行し、 DB操作をスキップして 200 OK を返す。疎通確認用。

Request Body schema: application/json
required
organization_id
string non-empty

計測タグ (POST /api/tracking/lead-status) で送ったのと同じ組織 ID。 system-managed カスタムフィールド「組織ID」で顧客を突合する。 PUT /referrals/leads/status の同名パラメータと同じ値をそのまま使えるため、 「有料転換で won にする → 売上を送る」を同じキーで通せる。 Stripe Webhook の 1段目照合 (metadata.jolt_organization_id) とも同じ突合キー。 同じ値の顧客がプログラム内に複数ある場合は最新の顧客を対象にする。

customer_id
string

Referral Customer ID（Jolt 内部 ID）

referral_id
string

Referral ID（Jolt 内部 ID）。紐付く Referral Customer を特定する。

custom_field_id
string

カスタムフィールド ID（ULID）

custom_field_value
string

カスタムフィールドの値

sales_amount
required
integer <int32> >= 0

紹介売り上げ金額

Array of objects (TransactionCustomFieldValueInput)

取引種別などの取引レコードカスタムフィールド値。 取引レコード作成後に報酬作成が非同期で走るため、値はこの作成リクエストに同梱する。 プログラムに項目が定義されていない場合や、他プログラムの項目・選択肢を指定した場合は 404 を返す。 同じ項目を2回指定した場合は 400 を返す。未指定は「取引種別なし」として扱う。

Responses

Request samples

Content type
application/json
Example
{
  • "customer_id": "01KB1S3TSZ4KMW6TR84KF6KPXC",
  • "sales_amount": 50000
}

Response samples

Content type
application/json
Example
{ }

ReferralCustomFieldValue

カスタムフィールド値の操作

カスタムフィールド値更新

指定した Referral のカスタムフィールド値を更新する。 部分更新をサポートし、指定されたフィールドのみ更新される。 存在しない値は新規作成、既存の値は上書きされる。

Authorizations:
apiKeyAuth
header Parameters
X-Dry-Run
string
Value: "true"
Example: true

true を指定すると、認証およびリクエストバリデーションのみ実行し、 DB操作をスキップして 200 OK を返す。疎通確認用。

Request Body schema: application/json
required
referral_id
required
string

Referral ID（ULID）

required
Array of objects

更新するカスタムフィールド値の配列

Responses

Request samples

Content type
application/json
{
  • "referral_id": "01KB1S3TSZ4KMW6TR84KF6KPXC",
  • "custom_field_values": [
    ]
}

Response samples

Content type
application/json
Example
{ }

ReferralActivityLog

活動ログの操作

活動ログ作成

紹介に対する活動ログを作成する。 Vendor / VendorProgram の整合性が取れない場合は 404 を返す。

Authorizations:
apiKeyAuth
header Parameters
X-Dry-Run
string
Value: "true"
Example: true

true を指定すると、認証およびリクエストバリデーションのみ実行し、 DB操作をスキップして 200 OK を返す。疎通確認用。

Request Body schema: application/json
required
referral_id
required
string

Referral ID（ULID）

title
required
string

活動ログのタイトル

content
string

活動ログの内容

activity_date
required
string <date>

活動日（YYYY-MM-DD）

Responses

Request samples

Content type
application/json
{
  • "referral_id": "01KB1S3TSZ4KMW6TR84KF6KPXC",
  • "title": "初回訪問",
  • "content": "初回訪問を実施し、サービス概要を説明しました。",
  • "activity_date": "2025-06-15"
}

Response samples

Content type
application/json
Example
{ }

MeetingTranscript

商談トランスクリプトの取り込み。Zapier / Make 等の自動化ツール経由で、議事録ツール （Notta / Fathom / tl;dv / Circleback 等）の文字起こしを受け取り、LLMで活動ログ下書きを 生成する。ベンダーが確認・確定するまでパートナーには公開されない。

商談トランスクリプト取り込み

商談の文字起こしを取り込む。必須は transcript のみ。マッチング（リード候補の絞り込み）は 同期処理で即座にレスポンスへ含めるが、要約（LLM呼び出し）はSQS経由の非同期処理のため、 本APIのレスポンスには含まれない。

マッチングは会議タイトル・参加者（メール／氏名）のみを対象に行う。トランスクリプト本文は 対象にしない。タイトル・参加者のいずれにもリードとの一致が無い商談は取り込まない （meeting_transcripts を作成せず、{"ingested": false, "reason": "no_match"} を返す）。

冪等キーは (vendor_program_id, external_source_id)。 external_source_id が無い場合は本文のハッシュを代替キーにする。同一キーでの再送は 新規作成せず、既存の取り込み結果をそのまま返す（この冪等性は取り込み済み＝meeting_transcripts が作成された場合にのみ働く。取り込まなかった場合は行自体が存在しないため、同じ入力を 再送すればその都度マッチング判定を再実行する。副作用が無いため結果は毎回同じになる）。

referral_id を直接指定する引数は無い（候補提示型。自動確定はしない）。

Authorizations:
apiKeyAuth
header Parameters
X-Dry-Run
string
Value: "true"
Example: true

true を指定すると、認証およびリクエストバリデーションのみ実行し、 DB操作をスキップして 200 OK を返す。疎通確認用。

Request Body schema: application/json
required
transcript
required
string

文字起こし本文。要約の対象

Array of objects (MeetingTranscriptParticipant)

参加者一覧。欠けるとマッチング優先度1（メール完全一致）・2・3（担当者氏名の完全一致）・ 5（メールドメイン一致）が使えず、会議タイトルの部分一致だけが手がかりになる。

title
string

会議タイトル。マッチングの手がかりが1つ減る

started_at
string

商談日時。RFC3339を推奨するが、date-only（YYYY-MM-DD）・オフセット無し （YYYY-MM-DDTHH:mm:ss）・空白区切り（YYYY-MM-DD HH:mm:ss）・Unixタイムスタンプ （秒/ミリ秒）も解釈する。オフセットを含まない形式はJST基準で解釈する。 どの形式でも解釈できない場合はエラーにはせず未設定として扱う（欠けると活動日が 受信日時になる。商談日と数日ずれうる）

external_source_id
string <= 255 characters

議事録ツール側の会議ID。冪等キー。欠けるとZapierの再送で二重取り込みが 起きうる（本文のハッシュを代替キーにするため実害は無いが、正確な照合のため指定を推奨）。 255文字を超える場合は external_source_id_too_long で400を返す（冪等キーのため 切り詰めると別の商談と同一キーになりうる）。 空文字・空白のみの場合は未指定として扱う（Zapier / Make のマッピングで 会議IDが取れなかったときに空文字が入ることがあるため。空文字のまま冪等キーに 使うと、会議IDを持たない別々の商談どうしが同一キーとして衝突する）。

Responses

Request samples

Content type
application/json
{
  • "transcript": "本日はお時間いただきありがとうございます。...",
  • "title": "株式会社山田商事様 定例商談",
  • "started_at": "2026-08-24T10:00:00+09:00",
  • "external_source_id": "meeting-abc123",
  • "participants": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "meeting_transcript_id": "01KB1S3TSZ4KMW6TR84KF6KPXC",
  • "match_candidates": [
    ]
}

Tag

クライアントサイトに埋め込む JS タグ (https://tag.jolt.me/v1/tag.js) から呼ばれる公開エンドポイント。 program_token (パブリックトークン) でベンダープログラムを識別する。書き込み専用権限。

タグ経由のリードステータス更新

クライアントサイトに埋め込んだ Jolt タグ (tag.js) から呼ばれる公開エンドポイント。 無料サインアップ完了 → qualified のステータスを更新する。

認証

APIキー不要。ボディの program_token (パブリックトークン pub_... 48文字) でベンダープログラムを識別する。 書き込み専用なので漏洩時の被害は当該プログラムのリードステータス変更に限定される。

won はこの経路では受け付けない (400)

program_token はベンダーのページソースから誰でも読める公開値である一方、won は 「顧客レコードの作成」「取引成立報酬の発火」「ダッシュボード上の成約表示」を伴うため、 報酬を承認する人が見る根拠そのものを外部から作れてしまう。 有料化の連携は API キー認証のある PUT /referrals/leads/status を使う。 リードの特定は、この経路で登録済みの organization_id を custom_field_id（カスタムフィールド「組織ID」）+ custom_field_value に指定すればよい。

仕様

  • 更新のみ: 既存の Referral / ReferralLead がない場合は 200 を返してサイレント終了（突合キーの存在確認には使えない設計）。
  • 突合キー: organization_id または email のいずれか必須。両方未指定なら 400。
    • 一次キー: organization_id (system-managed カスタムフィールド「組織ID」と照合)
    • フォールバック: organization_id 不一致 or 未指定なら email (Referral.contact_email) で再検索
    • 推奨運用: BtoB SaaS では無料サインアップ操作者と有料化操作者が別人になり得るため、organization_id を常時送信し、email 単独で運用しない
  • 冪等: 同じステータスの再送は backend 側で握り潰す（200 {} を返す）。毎ページビューで発火させてよい。サーバー間 API で won にした後にこの経路から qualified を送る後退遷移も同様に無視される。
  • レート制限: program_token は公開値のため単位時間あたりの呼び出し数に上限がある。超過時は 429。
  • organization_id: 外部サービスの組織 ID。リードの突合 (上記) に使われる。ここで送った値は system-managed カスタムフィールド「組織ID」として保存され、以降 PUT /referrals/leads/status や POST /referral-transactions の custom_field_value にそのまま使える (このフィールドは初回の upsert 時に自動作成される)。Stripe 連携を併用する場合は同じ値を Stripe metadata の jolt_organization_id キーにも送ること (キー名はレイヤで分離: Jolt API 内では organization_id、Stripe 共有名前空間では jolt_ プレフィックス付き)。ステータス遷移が不正な場合もこのフィールドのみ upsert される（タグの冪等性のため）。
  • 任意フィールド (company_name / last_name / first_name): 値が空でなければ Referral 上書き。

CORS

クロスドメインから呼ばれるためプリフライト OPTIONS を許可。credentials: omit でアクセスする想定。

Request Body schema: application/json
required
Any of
program_token
required
string^pub_[a-f0-9]{48}$

ベンダープログラムのパブリックトークン。 形式: pub_ プレフィックス + 48文字の小文字 16進数 (24-byte ランダム値の hex)。 ベンダーダッシュボード → プログラム設定 → 基本設定 → 「パブリックトークン」で確認できる。

organization_id
required
string non-empty

外部サービスの組織 ID。リードの突合一次キー (system-managed カスタムフィールド「組織ID」と照合)。 BtoB SaaS で人事異動・退職に対しても安定した識別子であり、サインアップ操作者と有料化操作者が別人になるケースでも won 遷移を取りこぼさないために強く推奨。 Stripe 連携の Webhook 1段目照合 (metadata.jolt_organization_id) と同じ値を送ること。 キー名はレイヤで分離: Jolt API 内では organization_id、Stripe 共有名前空間では jolt_ プレフィックス付き。 タグの冪等性のため、ステータス遷移が不正な場合でもこのフィールドのみ upsert される。 organization_id または email のいずれか必須 (空文字は未指定扱い、両方空なら 400)。

email
string <email> [ 1 .. 254 ] characters

ユーザーのメールアドレス。突合キーのフォールバック (既存リードの contact_email と一致するもの)。 organization_id が指定されていれば一次キーとしてはそちらが優先される。 organization_id または email のいずれか必須 (空文字は未指定扱い、両方空なら 400)。

status
required
string
Value: "qualified"

タグから設定可能なリードステータスは qualified（サインアップ完了 / 適格・進行中）のみ。

won（有料化完了）は このブラウザ経路では指定できない（400）。 program_token はベンダーのページソースから誰でも読める公開値である一方、 won は顧客レコードの作成・取引成立報酬の発火・ダッシュボード上の成約表示を伴うため。 有料化は API キー認証のある PUT /referrals/leads/status から更新する。

その他の値（new / unqualified / lost）もタグからは指定不可（400）。

company_name
string

会社名（任意 / 既存値を上書き）

last_name
string

担当者姓（任意 / 既存値を上書き）

first_name
string

担当者名（任意 / 既存値を上書き）

Responses

Request samples

Content type
application/json
Example
{
  • "program_token": "pub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  • "organization_id": "org_12345",
  • "email": "user@example.com",
  • "status": "qualified",
  • "company_name": "株式会社サンプル",
  • "last_name": "山田",
  • "first_name": "太郎"
}

Response samples

Content type
application/json
{ }

タグ経由のコンバージョンイベント発火（ブラウザ）

BtoC モード用のブラウザタグ公開エンドポイント。jolt-tag JS の jolt('track', '<event_name>', { amount }) から cross-origin POST で発火し、 Cookie (jolt_referral) の帰属情報を元に Referral / ConversionEvent を作成する。

旧仕様の /v1/tag/events/{signup,purchase,renewal} は廃止され、単一エンドポイントへ統合された。 イベント種別はパスではなく event_name（ベンダーが作成したコンバージョンイベント定義の slug）で指定する。

認証

APIキー不要。Cookie ベースの帰属解決のみ。vendor_program_id をボディに含める。

帰属解決と早期終了 (200)

以下のいずれかに該当する場合は ConversionEvent を作成せず、200 {success:true, status:"not_attributed"} でサイレント終了する (クロステナント誤帰属防止):

  • Cookie jolt_referral 未設定 (紹介経由でない直接アクセス)
  • Cookie の referrer_id / click_id / program_id のいずれかが空
  • Cookie の program_id がリクエスト vendor_program_id と一致しない

仕様

  • vendor_program_id / event_name / customer_contact_email 必須。
  • event_name は当該プログラムに存在するコンバージョンイベント定義の slug。未存在なら 404。
  • 帰属解決成功時は Referral を作成 (既存があれば再利用) し ConversionEvent を作成する。
  • 冪等性は external_source + external_source_id で担保（同一なら同一 ConversionEvent を返し status=idempotent_skip）。
  • 設定された Flow に応じてリファラー報酬を発火する。
  • 200 レスポンスの status は not_attributed / created / idempotent_skip のいずれか。

CORS

クロスドメインから呼ばれるためプリフライト OPTIONS を許可。credentials: include で Cookie を送ること。

Request Body schema: application/json
required
vendor_program_id
required
string

ベンダープログラムID (ULID)

event_name
required
string

コンバージョンイベント定義の slug（例 signup / purchase / renewal / 任意のカスタム slug）

customer_contact_email
required
string <email>

顧客連絡先メールアドレス

customer_name
string

顧客名

customer_contact_last_name
string

顧客担当者 姓

customer_contact_first_name
string

顧客担当者 名

amount
integer <int32> >= 0

購入金額等。パーセンテージ報酬の計算に使われる（0 / 未指定だと計算結果が 0 になり報酬は発火しない）。

external_source
string

ベンダー側ソース識別子（例 app / stripe）。external_source_id と合わせて冪等性に使う。

external_source_id
string

ベンダー側冪等 ID（例 order_12345）

metadata
string

任意の追加メタデータ。有効な JSON 文字列として送信する必要がある（例 '{"plan":"pro"}'）。 実装側で JSON としてバリデーションされ、不正な場合は 400 となる。

referral_code
string

紹介コード（任意）。プログラムが「紹介コード方式」で、Cookie が引き継げない構成 （別ドメイン・iframe 等）の BtoC 帰属で使う。指定があると Cookie ではなくコードで リファラーを特定して帰属する（大文字小文字・全角半角は吸収）。無指定なら従来どおり Cookie 帰属。

Responses

Request samples

Content type
application/json
Example
{
  • "vendor_program_id": "01JCK1S3TSZ4KMW6TR84KF6PR1",
  • "event_name": "signup",
  • "customer_contact_email": "customer@example.com"
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "status": "created",
  • "referral_id": "01JCK1S3TSZ4KMW6TR84KF6R01",
  • "conversion_event_id": "01JCK1S3TSZ4KMW6TR84KF6CE1",
  • "conversion_event_definition_id": "01JCK1S3TSZ4KMW6TR84KF6D01"
}

サーバー経由のコンバージョンイベント発火（API キー認証）

サーバーサイド呼び出し専用エンドポイント (Stripe Webhook 等)。Cookie を使わず customer_contact_email で既存紹介を解決する。任意の external_source / external_source_id で ConversionEvent を作成できるため API キー認証 (X-Jolt-API-Key) を必須化し、 リクエストの vendor_program_id が API キーの所属プログラムと一致することをサーバー側で再検証する。

認証

X-Jolt-API-Key 必須。キーの所属 vendor_program_id とリクエストの vendor_program_id が 一致しない場合は 403。

仕様

  • vendor_program_id / event_name / customer_contact_email / external_source / external_source_id 必須。
  • customer_contact_email で既存紹介 (Referral) を解決する。該当が無い場合は未帰属として status=not_attributed。
  • 冪等性は external_source + external_source_id で担保（status=idempotent_skip）。
Authorizations:
apiKeyAuth
Request Body schema: application/json
required
vendor_program_id
required
string
event_name
required
string

コンバージョンイベント定義の slug

customer_contact_email
required
string <email>

既存紹介との突合キー

amount
integer <int32> >= 0

継続課金額等。0 以上のみ受け付ける。

external_source
required
string

必須。ベンダー側ソース識別子（例 stripe）

external_source_id
required
string

必須。ベンダー側冪等 ID（例 in_xxx）

metadata
string

任意の追加メタデータ。有効な JSON 文字列として送信する必要がある。 実装側で JSON としてバリデーションされ、不正な場合は 400 となる。

referral_code
string

紹介コード（任意）。プログラムが「紹介コード方式」のとき、customer_contact_email での 既存紹介解決の代わりにコードでリファラーを特定して帰属する。自社システムからの BtoC 送信で、初回イベントからコードで帰属したい場合に使う。

Responses

Request samples

Content type
application/json
{
  • "vendor_program_id": "01JCK1S3TSZ4KMW6TR84KF6PR1",
  • "event_name": "renewal",
  • "customer_contact_email": "customer@example.com",
  • "amount": 5000,
  • "external_source": "stripe",
  • "external_source_id": "in_xxxxxxxxxxxx",
  • "metadata": "{\"cycle\":\"monthly\"}"
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "status": "created",
  • "referral_id": "01JCK1S3TSZ4KMW6TR84KF6R01",
  • "conversion_event_id": "01JCK1S3TSZ4KMW6TR84KF6CE1",
  • "conversion_event_definition_id": "01JCK1S3TSZ4KMW6TR84KF6D01"
}

StripeWebhook

Stripe Dashboard で登録する Webhook 受信先。決済成功・返金イベントを受けて取引レコード／報酬実績を作成する。

購読するイベント

Jolt が処理するのは以下の 2 つのみ。Stripe Dashboard でもこの 2 つだけを選択する。

イベント 用途
payment_intent.succeeded 一回払い・サブスク両方の決済成功 → 取引レコード作成
charge.refunded 返金 → 全額返金は論理削除、部分返金は残金額で再作成

紹介レコードの照合（3段階フォールバック）

Webhook 受信時、Jolt は以下の優先順位で紹介レコードを特定する：

  1. metadata.jolt_organization_id — クライアントサービスの組織 ID。Stripe metadata は他サービス共有名前空間のため jolt_ プレフィックスで衝突回避
  2. customer (Stripe顧客ID) — 既存クライアントとの後方互換
  3. billing_details.email — 最終フォールバック (payment_intent.succeeded イベントには含まれないため、実質サブスクでは効かない)

クライアント実装での metadata 付与

重要：Stripe の Customer.metadata は PaymentIntent に自動伝播しない。 Customer のみに metadata を付与しても、payment_intent.succeeded イベントの metadata フィールドは空となり 1段目の照合が機能しない。

確実に 1段目で照合するには、PaymentIntent 作成時にも metadata を設定する：

// Customer 作成時 (任意 — 監査用)
const customer = await stripe.customers.create({
  email: 'user@example.com',
  metadata: { jolt_organization_id: organization_id }
});

// 一回払い: PaymentIntent に必ず付与
await stripe.paymentIntents.create({
  amount, currency, customer: customer.id,
  metadata: { jolt_organization_id: organization_id }   // ← 必須
});

// サブスク (Checkout 経由): payment_intent_data.metadata に付与
// (Stripe は内部で各請求サイクル毎に PaymentIntent を作成し、その metadata がイベントに載る)
await stripe.checkout.sessions.create({
  mode: 'subscription',
  customer: customer.id,
  line_items: [...],
  payment_intent_data: {
    metadata: { jolt_organization_id: organization_id } // ← 必須
  }
});

※ Stripe metadata に乗せる値は、タグ API (POST /api/tracking/lead-status) の organization_id と 同じ値を送ること。両者は同じ「クライアントサービスの組織 ID」を表し、それぞれのレイヤで名前空間を分けるためにキー名だけ異なる:

  • タグ API リクエストパラメータ: organization_id (Jolt API 内なので Jolt は自明)
  • Stripe metadata キー: jolt_organization_id (他サービスと共有名前空間のため Jolt プレフィックス)

署名検証

Stripe Dashboard でこの Webhook 受信先を登録時に発行される署名シークレット（whsec_...）を、Jolt 管理画面の Stripe 連携設定にも登録する必要がある。 ステージング環境のみ、STRIPE_WEBHOOK_SKIP_SIGNATURE_VERIFICATION=true で署名検証をスキップ可能（playground 検証用）。本番環境では絶対に有効化されない。

Stripe Webhook 受信

Stripe Dashboard で登録する Webhook 受信先。 決済成功・返金イベントを受信して、紹介レコードに紐付く取引レコードと報酬実績を自動作成する。

設定手順

  1. Stripe Dashboard → Developers → Webhooks → Add endpoint
  2. URL に https://external-api.jolt.me/integrations/stripe/webhook/<vendor_program_id> を設定
  3. 「Listen to events on your account」で payment_intent.succeeded と charge.refunded の 2 つだけ を選択
  4. 発行された署名シークレット (whsec_...) を Jolt 管理画面の Stripe 連携設定に登録

処理対象イベント

  • payment_intent.succeeded: 一回払い・サブスクの決済成功 → 取引レコード作成 + 報酬実績作成
  • charge.refunded (全額返金): 取引レコード + 報酬実績を論理削除
  • charge.refunded (部分返金): 取引レコード + 報酬実績を論理削除し、残金額で再作成

紹介レコードの特定（3段階フォールバック）

詳細は StripeWebhook タグの説明を参照。要約：

  1. metadata.jolt_organization_id → 1段目（Stripe metadata は他サービス共有名前空間のため Jolt プレフィックス付き）
  2. customer (Stripe顧客ID) → 2段目（既存クライアント後方互換）
  3. billing_details.email → 3段目（最終フォールバック、payment_intent.succeeded には含まれない）

レスポンス

Stripe のリトライ抑止のため、内部処理が失敗しても基本的に 200 を返す（イベントは stripe_events テーブルに記録される）。

path Parameters
vendor_program_id
required
string
Example: 01K9YHPWKGF330PR9222K49J31

ベンダープログラムID (ULID)。Stripe 連携設定の宛先プログラムを特定する。

header Parameters
Stripe-Signature
required
string

Stripe が付与する署名ヘッダ。whsec_... シークレットで検証される。 staging 環境で STRIPE_WEBHOOK_SKIP_SIGNATURE_VERIFICATION=true の場合のみ省略可（playground 用、本番では不可）。

Request Body schema: application/json
required

Stripe が送信するイベントオブジェクト（Event object）。 Jolt 側では data.object.metadata.jolt_organization_id などを参照するが、エンベロープ全体は Stripe 仕様に従う。

id
string

Stripe イベント ID

type
string
Enum: "payment_intent.succeeded" "charge.refunded"

イベントタイプ

livemode
boolean

本番モードかどうか

object

イベント本体（data.object に Stripe オブジェクトが入る）

Responses

Request samples

Content type
application/json
{
  • "id": "evt_1Abc...",
  • "type": "payment_intent.succeeded",
  • "livemode": true,
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "status": "ok"
}

WebhookEvents

登録された Webhook URL に送信されるイベントペイロード。 各イベントは共通の Envelope 構造でラップされ、type フィールドでイベント種別を識別できます。 Webhook 受信側は HTTP 200 を返却してください。

リード作成イベント

新しいリード（紹介案件）が作成された際に送信されるイベント。 type: "lead.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "lead.created"

イベント種別: lead.created(新規リード作成時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (LeadCreatedData)

リード作成イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "lead.created",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

リードステータス更新イベント

リードのステータスが更新された際に送信されるイベント。 type: "lead.status"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "lead.status"

イベント種別: lead.status(リードステータス更新時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (LeadStatusData)

リードステータス更新イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "lead.status",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

報酬作成イベント

新しい報酬レコードが作成された際に送信されるイベント。 type: "reward.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "reward.created"

イベント種別: reward.created(新規報酬作成時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (RewardCreatedData)

報酬作成イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "reward.created",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

報酬ステータス更新イベント

報酬のステータスが更新された際に送信されるイベント。 type: "reward.status"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "reward.status"

イベント種別: reward.status(報酬ステータス更新時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (RewardStatusData)

報酬ステータス更新イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "reward.status",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

パートナープログラム申請イベント

パートナーがベンダープログラムに申請した際に送信されるイベント。 type: "vendor_program.partner.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "vendor_program.partner.created"

イベント種別: vendor_program.partner.created(プログラムにパートナーが申請時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (VendorProgramPartnerCreatedData)

パートナープログラム申請イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "vendor_program.partner.created",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

パートナーステータス更新イベント

パートナーのプログラム参加ステータスが更新された際に送信されるイベント。 type: "vendor_program.partner.status"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "vendor_program.partner.status"

イベント種別: vendor_program.partner.status(プログラム参加中パートナーステータス更新時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (VendorProgramPartnerStatusData)

パートナーステータス更新イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "vendor_program.partner.status",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

活動ログ作成イベント

新しい活動ログが作成された際に送信されるイベント。 type: "referral_activity_log.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "referral_activity_log.created"

イベント種別: referral_activity_log.created(新規活動ログ作成時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ActivityLogCreatedData)

活動ログ作成イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "referral_activity_log.created",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

リファラー リード作成イベント

リファラー経由のリンクから新しいリードが作成された際に送信されるイベント。 パートナー経由の lead.created とは別イベントとして発火するため、リファラー経由のリードだけを別ルートに流せる。 type: "referrer.lead.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "referrer.lead.created"

イベント種別: referrer.lead.created(リファラー経由のリンクからリード作成時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ReferrerLeadCreatedData)

リファラー リード作成イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "referrer.lead.created",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

リファラー登録イベント

リファラー（紹介者）が新規登録された際に送信されるイベント。 type: "referrer.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "referrer.created"

イベント種別: referrer.created(リファラー新規登録時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ReferrerCreatedData)

リファラー登録イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "referrer.created",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

リファラー認証完了イベント

リファラーがマジックリンク認証を完了した際に送信されるイベント。 type: "referrer.verified"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "referrer.verified"

イベント種別: referrer.verified(リファラーがマジックリンク認証を完了した時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ReferrerVerifiedData)

リファラー認証完了イベントのデータ

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "referrer.verified",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

リファラーブロックイベント

リファラーがベンダーによってブロックされた際に送信されるイベント。 type: "referrer.blocked"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "referrer.blocked"

イベント種別: referrer.blocked(リファラーがブロックされた時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ReferrerStatusData)

リファラーステータス更新イベントのデータ（blocked / unblocked 共通）

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "referrer.blocked",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

リファラーブロック解除イベント

リファラーのブロックが解除された際に送信されるイベント。 type: "referrer.unblocked"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "referrer.unblocked"

イベント種別: referrer.unblocked(リファラーのブロック解除時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ReferrerStatusData)

リファラーステータス更新イベントのデータ（blocked / unblocked 共通）

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "referrer.unblocked",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

コンバージョンイベント作成

ベンダー (BtoC) でコンバージョンイベントが作成された際に送信されるイベント。 signup / purchase / custom / renewal のいずれも conversion_event.created 単一イベントとして発火し、サブタイプは data.event_type で識別する。 type: "conversion_event.created"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "conversion_event.created"

イベント種別: conversion_event.created

sent_at
required
string <date-time>

送信日時 (JST)。実装は time.Now().In(JST) で生成するため、Z ではなく +09:00 オフセット付きで出力される。

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (ConversionEventCreatedData)

コンバージョンイベント作成のデータ。signup / purchase / custom / renewal で共通フィールド構造。

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "conversion_event.created",
  • "sent_at": "2025-01-15T18:30:00+09:00",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {
    }
}

商談トランスクリプト要約完了イベント

商談トランスクリプトの要約(LLM)が完了した際に送信されるイベント。活動ログの確定前（要対応の段階）に発火する点が他のイベントと異なり、要約本文（下書きのtitle/content）は一切含まない。 type: "meeting_transcript.summary_ready"

Request Body schema: application/json
required
id
required
string

イベントID (ULID)

type
required
string
Value: "meeting_transcript.summary_ready"

イベント種別: meeting_transcript.summary_ready(要約完了時)

sent_at
required
string <date-time>

送信日時

required
object (WebhookVendor)

ベンダー情報

required
object (WebhookVendorProgram)

ベンダープログラム情報

required
object (MeetingTranscriptSummaryReadyData)

商談トランスクリプト要約完了イベントのデータ。要約本文（下書きのtitle/content）は一切含まない。

Responses

Request samples

Content type
application/json
{
  • "id": "01JCK1S3TSZ4KMW6TR84KF6EVT",
  • "type": "meeting_transcript.summary_ready",
  • "sent_at": "2025-01-15T09:30:00Z",
  • "vendor": {
    },
  • "vendor_program": {
    },
  • "data": {}
}