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回送信します。最小限のデータは次のとおりです。

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

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

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

作成した投稿のIDを含む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で公開先の設定を開く

画面上部のメニューからアカウントを選択します。接続セクションの公開先で公開先を管理を選択します。公開先設定ページから直接開くこともできます。

2. 公開先を追加する

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

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

次の項目を入力します。

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

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

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

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

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

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

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

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

接続テストで確認できるのは以下の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も返されていれば、それも一緒に伝えます。

公開のツールの引数については、ツールリファレンスの公開をご覧ください。

既存の投稿を更新する

エージェントに記事の更新を依頼し、最初の公開時に返された 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秒待ち、再試行しません。タイムアウトやエラーレスポンスは失敗になります。

その他のエラーについては、トラブルシューティングをご覧ください。

連携を解除する

Kafkaiからの公開を停止するには、公開先設定ページで公開先の削除を選択してください。Kafkaiが公開済みの記事は、エンドポイント側に残ります。

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