# Webhookを連携する

WordPress以外のサイトに記事を公開する場合は、Webhookを使います。自分のCMSや静的サイトジェネレーター、ヘッドレスフロントエンド、または別のサービスに記事を転送するスクリプトなどを公開先に指定できます。

エンドポイントをKafkaiの公開先に追加すれば、AIエージェントが書いた記事をそのエンドポイントに送信できます。公開を指定しない限り、記事は下書きとして送信されます。サイト上で内容を確認してから、公開してください。

Kafkaiがエンドポイントに送信するには、以下が必要です。

- JSONボディの `POST` を受け付ける**アドレス**
- エンドポイントがログインを要求する場合は、**ユーザー名とパスワード**（KafkaiはHTTP Basic認証として送信します）

そのほかの設定は不要です。Kafkaiが記事を送信し、エンドポイントは作成した投稿のIDを返してください。

## 準備するもの

- インターネットからHTTPSで到達できるエンドポイント
- `Content-Type: application/json` の `POST` を受け付けるエンドポイント
- 作成した投稿のIDを含むJSONボディを返すエンドポイント
- 公開先をKafkaiの画面から追加するか、エージェントに `kafkai_add_publishing_destination` で追加させること

### エンドポイントが受け取る内容

記事を1件公開するたびに、Kafkaiは `POST` を1回送信します。最小限のデータは次のとおりです。

```json
{
  "title": "How to build an AI strategy",
  "content": "<p>Rendered HTML</p>",
  "status": "draft"
}
```

`status` の値は `draft` または `live` です。実際の送信データには、指定があれば `language`、`slug`、`categories`、エージェントが書いたままのMarkdown、記事の補足情報も含まれます。不要なフィールドは無視できます。フィールドの一覧は、ツールリファレンスの[Webhookのリクエストとレスポンス](https://kafkai.com/ja/docs/tools/#webhookのリクエストとレスポンス)をご覧ください。

### エンドポイントが返す内容

作成した投稿のIDを含むJSONです。

```json
{
  "id": "123",
  "url": "https://example.com/blog/how-to-build-an-ai-strategy"
}
```

- `id`（または `external_id`）：**必須**。作成した投稿のIDです。Kafkaiはこの値をエージェントに `external_id` として返し、あとから同じ投稿を更新するときに使います
- `url`：任意。投稿の公開URLまたはプレビューURLです。Kafkaiはこの値をエージェントに `external_url` として返します。指定がない場合、KafkaiはエンドポイントのURLを `external_url` として返します

Kafkaiが受け付けるHTTPステータスは `200`、`201`、`202` です。それ以外は失敗となります。失敗した場合、KafkaiはJSONのエラーボディの `error` または `message` フィールドをエージェントに表示します。ボディがJSONでない場合は、ステータスコードを表示します。成功ステータスでも、HTMLのレスポンス、JSON以外のデータ、IDの欠落はいずれも失敗となります。

### 更新も同じリクエスト

更新は、同じURLへの同じ `POST` で、`external_id` がボディに入るだけです。エンドポイントが作成か更新かを判断します。`external_id` があればその投稿を更新し、なければ新しく作成します。

## 1. Kafkaiで公開先の設定を開く

画面上部のメニューから**アカウント**を選択します。**接続**セクションの**公開先**で**公開先を管理**を選択します。[公開先設定ページ](https://kafkai.com/ja/accounts/publishing-destinations/)から直接開くこともできます。

<img src="https://kafkai.com/static/images/docs/connect/destinations-01-account-ja.webp" alt="Kafkaiのアカウント画面。メニューのアカウントと、接続の欄にある公開先の行が枠で囲まれている" width="800" loading="lazy">

## 2. 公開先を追加する

**公開先を追加**を選択します。

<img src="https://kafkai.com/static/images/docs/connect/destinations-02-add-destination-ja.webp" alt="公開先がまだない公開先設定の画面。公開先を追加のボタンが枠で囲まれている" width="800" loading="lazy">

## 3. エンドポイントの情報を入力する

次の項目を入力します。

| 項目 | 入力する内容 |
| --- | --- |
| **お名前** | 公開先の名前（例：`My blog webhook`）。エージェントが一覧を確認するときに見える名前です。 |
| **タイプ** | **Webhook** |
| **URL** | エンドポイントのアドレス（例：`https://example.com/hooks/articles`） |
| **認証** | **Basic認証** |
| **ユーザー名** | エンドポイントが要求するユーザー名 |
| **パスワード** | エンドポイントが要求するパスワード |

**保存前に接続テストを行う**にチェックを入れたまま、**保存**を選択します。

<img src="https://kafkai.com/static/images/docs/connect/webhook-03-form-ja.webp" alt="公開先を追加のフォーム。タイプはWebhook、認証はBasic認証で、ユーザー名とパスワードが入力され、保存前に接続テストを行うにチェックが入っている" width="520" loading="lazy">

**認証**はBasic認証のみです。Kafkaiが送信できるのはBasic認証だけです。このフォームでは、ユーザー名とパスワードは両方とも必須です。ログイン不要のエンドポイントの場合は、`kafkai_add_publishing_destination` で認証情報を指定せずに公開先を作成してください。この場合、Kafkaiは `Authorization` ヘッダーを送信しません。

Kafkaiはユーザー名とパスワードを暗号化して保存します。保存後は画面に表示せず、エージェントにも返しません。

これらの情報は、エージェントとのチャットではなく、この画面で入力してください。会話にパスワードが残らないためです。

## 4. 公開先が有効になったことを確認する

接続テストが成功すると、Kafkaiは公開先を保存します。一覧に「有効」ラベル、最終テスト日時、チェックマークが表示されます。

<img src="https://kafkai.com/static/images/docs/connect/webhook-04-active-ja.webp" alt="公開先設定の画面。Webhookの公開先が1件あり、有効のラベル、最終テストの日時とチェックマーク、テスト・編集・削除のリンクが表示されている" width="800" loading="lazy">

接続テストをやり直すには、**テスト**を選択します。

接続テストで確認できるのは以下の2点です。

- Kafkaiがエンドポイントに接続できること
- 認証情報が正しいこと

記事は公開されません。そのため、テストは通っても、公開が必ず成功するわけではありません。連携全体を確認するには、1件の下書きを公開してみてください。

### 接続テストの方法

Kafkaiはまずエンドポイントに `GET` を送信します。`200` または `201` の応答で成功です。`400` の応答も成功とみなします。到達はできているが、内容が異なるだけ、という意味です。エンドポイントが `GET` を受け付けずに `405` を返す場合は、代わりに `{"test": true}` というボディの `POST` を送信します。その応答が `200`、`201`、`202`、`400` のいずれかであれば成功です。

`404` を返すと、記事を受け取れる場合でもテストに失敗します。エラーの理由は `Endpoint not found` です。`POST` のみを受け付けるエンドポイントでは、`GET` には `405` で応答してください。

## 最初の下書きを公開する

エージェントに「テスト記事を書いて、Webhookに下書きで公開して」と伝えてください。

エージェントは `kafkai_list_publishing_destinations` で公開先を確認し、`kafkai_publish_article` で記事の本文を送信します。公開先の一覧取得と公開はいずれも無料です。エージェントは、エンドポイントが返した投稿IDを伝えます。URLも返されていれば、それも一緒に伝えます。

公開のツールの引数については、ツールリファレンスの[公開](https://kafkai.com/ja/docs/tools/#公開)をご覧ください。

## 既存の投稿を更新する

エージェントに記事の更新を依頼し、最初の公開時に返された `external_id` を渡してください。Kafkaiは同じURLに `external_id` 付きの `POST` を送信します。エンドポイントは新しい投稿を作らずに、既存の投稿を更新します。

言語ごとの `external_id` は別々に保管してください。2言語の記事は2つの投稿で、それぞれ別のIDを持ちます。

## 接続テストに失敗する場合

フォームに「接続テストに失敗しました:」と、失敗の理由が表示されます。

| 理由 | 確認する内容 |
| --- | --- |
| `Invalid credentials` | ユーザー名かパスワードが誤っています。エンドポイントが何を期待しているかを確認してください。 |
| `Access forbidden` | ファイアウォールまたはプロキシがリクエストを遮断しています。エンドポイントへのアクセスを許可してください。 |
| `Endpoint not found - please check the webhook URL` | URLが誤っているか、エンドポイントが `GET` に `404` を返しています。`POST` のみを受け付けるエンドポイントでは、`GET` には `405` で応答してください。 |
| `Webhook returned HTTP 500` | エンドポイントがエラーステータスを返しました。エンドポイント側のログを確認してください。 |
| `Cannot connect to webhook` | URLに入力ミスがあるか、エンドポイントにインターネットから到達できません。 |
| `Connection timeout` | エンドポイントが時間内に応答しませんでした。もう一度試してください。 |

ユーザー名とパスワードが正しいのに `Invalid credentials` になるときは、エンドポイントが読み取る前に、サーバーが認証情報を取り除いている可能性があります。サーバーが `Authorization` ヘッダーを渡しているかどうかを、ホスティング事業者に確認してください。

## 接続テストには成功するが公開に失敗する場合

`kafkai_publish_article` は、エンドポイントからのエラーをそのまま伝えます。

- **エンドポイントがエラーステータスを返した。** KafkaiはJSONのエラーボディの `error` または `message` フィールドを表示します。ボディがJSONでない場合は、ステータスコードを表示します。
- **エンドポイントが、成功ステータスでJSON以外のボディを返した。** 成功ステータスの場合はJSONボディが必要です。HTMLのレスポンス、ほかのContent-Type、JSONとして解釈できないデータは失敗となり、Kafkaiは返ってきた内容の先頭部分を表示します。
- **エンドポイントがIDを返さなかった。** JSONボディに `id` も `external_id` もない成功ステータスは失敗です。作成した投稿のIDを返す必要があります。
- **リクエストがタイムアウトした。** Kafkaiは応答を30秒待ち、再試行しません。タイムアウトやエラーレスポンスは失敗になります。

その他のエラーについては、[トラブルシューティング](https://kafkai.com/ja/docs/troubleshooting/)をご覧ください。

## 連携を解除する

Kafkaiからの公開を停止するには、[公開先設定ページ](https://kafkai.com/ja/accounts/publishing-destinations/)で公開先の**削除**を選択してください。Kafkaiが公開済みの記事は、エンドポイント側に残ります。

公開先は残して、一時的に公開を止めたい場合は、エンドポイント側の認証情報を削除してください。Kafkaiは `Authorization` ヘッダーを付けずに呼び出します。エンドポイント側で、認証なしのリクエストをどう扱うかを決められます。
