Gemlead
Docs
ログイン
APIキーを取得

APIリファレンス

Webhookエンドポイント

Webhookエンドポイントは、Gemleadのイベントを発生と同時に受け取る、あなたのURLです。1アカウントあたり10個まで登録できます。イベント、ペイロード、署名の検証方法についてはWebhookを参照してください。

エンドポイント

Webhookエンドポイントオブジェクト

Gemleadがイベントを送る、あなたのURL。イベントと検証方法についてはWebhookを参照してください。

属性

  • idstring
    エンドポイントの一意の識別子。
  • objectstring
    常にwebhook_endpointです。
  • urlstring
    イベントの送信先のHTTPS URL。
  • descriptionstringまたはnull
    エンドポイントについてのメモ。
  • eventsstringsの配列
    送信されるイベントタイプ。
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • statusstring
    イベントが送信されるかどうか。
    enableddisabled
  • filtersobject
    リードのペルソナで、受け取るイベントを指定します。すべてのイベントタイプに適用されます。
  • disabled_reasonstringまたはnull
    無効になっている理由。あなたがオフにした場合はmanual、3日連続で失敗し、失敗した試行が8回以上になってGemleadが無効にした場合はfailingです。有効な間はnullです。
    manualfailing
  • secretstring
    署名シークレット。whsec_に続く32文字です。作成時とシークレットの再発行時のレスポンスにのみ含まれます。
  • created_atstring
    エンドポイントが作成された日時。ISO 8601形式です。
  • updated_atstring
    エンドポイントが最後に変更された日時。ISO 8601形式です。
Webhookエンドポイントオブジェクト
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Webhookエンドポイントを一覧表示

GET/v1/webhook_endpointsreadスコープ

Webhookエンドポイントを、シークレットを除いて返します。

クエリパラメーター

  • limitinteger
    返すオブジェクトの数。1から100まで指定でき、デフォルトは25です。
  • cursorstring
    次のページを取得するための、前のページのnext_cursor。ページネーションを参照してください。

戻り値

Webhookエンドポイントオブジェクトのリスト。

GET/v1/webhook_endpoints
curl https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
レスポンス200
{
  "object": "list",
  "data": [
    {
      "id": "wh3LpX9dKe",
      "object": "webhook_endpoint",
      "url": "https://example.com/webhooks/gemlead",
      "description": "CRM sync",
      "events": ["lead.hot", "reply.received"],
      "status": "enabled",
      "filters": {
        "persona_ids": ["lvWBPnytpS"]
      },
      "disabled_reason": null,
      "created_at": "2026-09-14T09:21:05.300Z",
      "updated_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Webhookエンドポイントを作成

POST/v1/webhook_endpointswriteスコープ

1つ以上のイベントタイプを受け取るURLを登録します。レスポンスのsecretは、表示されるのがこの一度だけなので、必ず保存してください。

ボディパラメーター

  • urlstring必須
    公開インターネットから応答できるHTTPS URL。
  • eventsstringsの配列必須
    送信するイベントタイプ。
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • descriptionstring
    自分用のメモ。
  • filtersobject
    リードのペルソナで、送信するイベントを指定します。

戻り値

secretを含む、新しいWebhookエンドポイントオブジェクト。

エラー

  • 400parameter_missing
    必須パラメーターがありません。paramにその名前が入ります。
  • 400parameter_invalid
    APIが受け付けない値のパラメーターがあります。paramにその名前が入ります。
  • 400parameter_unknown
    ボディに、このエンドポイントが受け付けないフィールドがあります。
  • 400url_invalid
    URLがHTTPSでない、認証情報を含んでいる、またはプライベートアドレスを指しています。
  • 400webhook_endpoint_limit_reached
    アカウントにはすでに10個のエンドポイントがあります。
POST/v1/webhook_endpoints
curl -X POST https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/gemlead",
    "events": ["lead.hot", "reply.received"],
    "description": "CRM sync",
    "filters": {
      "persona_ids": ["lvWBPnytpS"]
    }
  }'
レスポンス200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z",
  "secret": "whsec_4QeX7nP2kR9tLm3Vb8YzC1dF6hJ0sWuA"
}

Webhookエンドポイントを取得

GET/v1/webhook_endpoints/:idreadスコープ

Webhookエンドポイントを1件、シークレットを除いて返します。

パスパラメーター

  • idstring必須
    WebhookエンドポイントのID。

戻り値

Webhookエンドポイントオブジェクト。

エラー

  • 404resource_missing
    キーのアカウントに、このIDのWebhookエンドポイントはありません。
GET/v1/webhook_endpoints/:id
curl https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
レスポンス200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Webhookエンドポイントを更新

PATCH/v1/webhook_endpoints/:idwriteスコープ

エンドポイントを変更します。Gemleadが無効にしたエンドポイントを再び有効にするには、statusをenabledにします。有効にするか新しいurlを指定すると、失敗のカウントはやり直しになります。

パスパラメーター

  • idstring必須
    WebhookエンドポイントのID。

ボディパラメーター

  • urlstring
    新しいHTTPS URL。
  • eventsstringsの配列
    送信するイベントタイプ。
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • descriptionstring
    自分用のメモ。
  • statusstring
    エンドポイントをオンまたはオフにします。
    enableddisabled
  • filtersobject
    リードのペルソナで、送信するイベントを指定します。

戻り値

更新されたWebhookエンドポイントオブジェクト。

エラー

  • 404resource_missing
    キーのアカウントに、このIDのWebhookエンドポイントはありません。
  • 400parameter_invalid
    APIが受け付けない値のパラメーターがあります。paramにその名前が入ります。
  • 400parameter_unknown
    ボディに、このエンドポイントが受け付けないフィールドがあります。
  • 400url_invalid
    URLがHTTPSでない、認証情報を含んでいる、またはプライベートアドレスを指しています。
PATCH/v1/webhook_endpoints/:id
curl -X PATCH \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "enabled"
  }'
レスポンス200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Webhookエンドポイントを削除

DELETE/v1/webhook_endpoints/:idwriteスコープ

エンドポイントを削除します。再試行を待っている配信は破棄されます。

パスパラメーター

  • idstring必須
    WebhookエンドポイントのID。

戻り値

エンドポイントのidと、trueに設定されたdeletedを含むオブジェクト。

エラー

  • 404resource_missing
    キーのアカウントに、このIDのWebhookエンドポイントはありません。
DELETE/v1/webhook_endpoints/:id
curl -X DELETE \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
レスポンス200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "deleted": true
}

署名シークレットを再発行

POST/v1/webhook_endpoints/:id/roll_secretwriteスコープ

エンドポイントのシークレットをすぐに置き換え、古いシークレットは使えなくなります。その間に失敗した配信は、新しいシークレットで署名されて再試行されます。

パスパラメーター

  • idstring必須
    WebhookエンドポイントのID。

戻り値

新しいsecretを含むWebhookエンドポイントオブジェクト。

エラー

  • 404resource_missing
    キーのアカウントに、このIDのWebhookエンドポイントはありません。
POST/v1/webhook_endpoints/:id/roll_secret
curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/roll_secret \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
レスポンス200
{
  "id": "wh3LpX9dKe",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/gemlead",
  "description": "CRM sync",
  "events": ["lead.hot", "reply.received"],
  "status": "enabled",
  "filters": {
    "persona_ids": ["lvWBPnytpS"]
  },
  "disabled_reason": null,
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z",
  "secret": "whsec_4QeX7nP2kR9tLm3Vb8YzC1dF6hJ0sWuA"
}

テストイベントを送信

POST/v1/webhook_endpoints/:id/testwriteスコープ

エンドポイントの最初のイベントタイプのサンプルイベントを、data.testをtrueに、IDをtest_で始まる値にして送信します。試行は1回のみで、再試行はありません。

パスパラメーター

  • idstring必須
    WebhookエンドポイントのID。

戻り値

エンドポイントが返したstatusとstatus_codeを含むWebhook配信オブジェクト。

エラー

  • 404resource_missing
    キーのアカウントに、このIDのWebhookエンドポイントはありません。
POST/v1/webhook_endpoints/:id/test
curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/test \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
レスポンス200
{
  "id": "dL5qW1zXa8",
  "object": "webhook_delivery",
  "endpoint_id": "wh3LpX9dKe",
  "event_id": "evt_8kQ2vXr4LmT9wPz1Hc6YbN3d",
  "event_type": "lead.hot",
  "status": "succeeded",
  "attempts": 1,
  "status_code": 200,
  "error": null,
  "test": true,
  "next_attempt_at": null,
  "last_attempt_at": "2026-11-06T07:45:12.904Z",
  "created_at": "2026-11-06T07:45:12.904Z"
}

Webhook配信オブジェクト

1つのエンドポイントに送られた1件のイベント。試行の状況と、サーバーからの最後の応答を含みます。

属性

  • idstring
    配信の一意の識別子。
  • objectstring
    常にwebhook_deliveryです。
  • endpoint_idstring
    送信先のエンドポイント。
  • event_idstring
    送信されたイベント。サーバーが受け取ったidです。
  • event_typestring
    イベントのタイプ。
    lead.createdlead.hotreply.receivedreaction.receivedsam.suggestion.readysam.reply.sentsam.handoff
  • statusstring
    試行が残っている間はpending、その後はsucceededまたはfailedです。
    pendingsucceededfailed
  • attemptsinteger
    これまでの試行回数。最大8回です。
  • status_codeintegerまたはnull
    最後の応答のHTTPステータス。タイムアウトや接続エラーで応答がなかった場合はnullです。
  • errorstringまたはnull
    最後の試行で起きた問題。ステータスと応答の冒頭部分、またはタイムアウトなどです。
  • testboolean
    テストイベントの場合はtrue。
  • next_attempt_atstringまたはnull
    pendingの間の、次の試行の予定日時。
  • last_attempt_atstringまたはnull
    最後に試行した日時。
  • created_atstring
    配信が作成された日時。ISO 8601形式です。
Webhook配信オブジェクト
{
  "id": "dR7mK2pVn4",
  "object": "webhook_delivery",
  "endpoint_id": "wh3LpX9dKe",
  "event_id": "evt_3Hn7QpW2xZk9LmR4tV8bYc1D",
  "event_type": "reply.received",
  "status": "pending",
  "attempts": 2,
  "status_code": 503,
  "error": "HTTP 503: Service Unavailable",
  "test": false,
  "next_attempt_at": "2026-11-06T08:18:10.000Z",
  "last_attempt_at": "2026-11-06T08:13:10.000Z",
  "created_at": "2026-11-06T08:12:10.000Z"
}

配信を一覧表示

GET/v1/webhook_endpoints/:id/deliveriesreadスコープ

エンドポイントの最近の配信を、テストイベントも含めて新しい順に返します。配信は30日間保持されます。

パスパラメーター

  • idstring必須
    WebhookエンドポイントのID。

クエリパラメーター

  • limitinteger
    返す配信の数。1から100まで指定でき、デフォルトは25です。

戻り値

Webhook配信オブジェクトのリスト。このリストにはnext_cursorがないため、さらに表示するにはlimitを増やしてください。

エラー

  • 404resource_missing
    キーのアカウントに、このIDのWebhookエンドポイントはありません。
  • 400parameter_invalid
    APIが受け付けない値のパラメーターがあります。paramにその名前が入ります。
GET/v1/webhook_endpoints/:id/deliveries
curl -G \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/deliveries \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d limit=10
レスポンス200
{
  "object": "list",
  "data": [
    {
      "id": "dR7mK2pVn4",
      "object": "webhook_delivery",
      "endpoint_id": "wh3LpX9dKe",
      "event_id": "evt_3Hn7QpW2xZk9LmR4tV8bYc1D",
      "event_type": "reply.received",
      "status": "pending",
      "attempts": 2,
      "status_code": 503,
      "error": "HTTP 503: Service Unavailable",
      "test": false,
      "next_attempt_at": "2026-11-06T08:18:10.000Z",
      "last_attempt_at": "2026-11-06T08:13:10.000Z",
      "created_at": "2026-11-06T08:12:10.000Z"
    },
    {
      "id": "dL5qW1zXa8",
      "object": "webhook_delivery",
      "endpoint_id": "wh3LpX9dKe",
      "event_id": "evt_8kQ2vXr4LmT9wPz1Hc6YbN3d",
      "event_type": "lead.hot",
      "status": "succeeded",
      "attempts": 1,
      "status_code": 200,
      "error": null,
      "test": true,
      "next_attempt_at": null,
      "last_attempt_at": "2026-11-06T07:45:12.904Z",
      "created_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
Gemleadの最新情報を
メールで直接お届けします。
登録
登録すると、プライバシーポリシーに同意し、当社からのお知らせの受信を承諾したものとみなされます。
Gemlead
製品
始める
ログイン
こんな方に
AIエージェント
機能
料金
アフィリエイト
FAQ
機能
24時間、買い手を発見ホットリード優先返信率60%超え心を読むDM全DMをひとつにAIクローザー限界なくスケールAPI・MCP・WebhookGemleadに質問
リソース
ホームAPIブログ
法的情報
利用規約
プライバシー
© 2026 Gemlead, Inc. 無断転載を禁じます。
日本語