| On this page |
New
この機能は、License Server 20.0で追加されました。
組織が成長するにつれて、ライセンスのニーズも高まります。ライセンスがどのように使用されているのか、またライセンスサーバーがどのように機能しているかを深く理解したい場合、Webhookを使用するとわかりやすくなります。ライセンスサーバーは1つのWebhookをサポートし、複数のイベントにサブスクライブ可能です。
Webhookをセットアップするには、hkeyを開きます。
-
File ▸ Webhooks… をクリックして、Webhookダイアログを開きます。
-
ダイアログの上部でWebhook URLを入力します。例えば、
https://mycompany.sidefx.webhook:8080/などです。 -
受信したい任意の数のトリガーにサブスクライブします。
URLの検証 ¶
WebhookのURLを設定する時、イベントを送信する前に、そのURLが実際に有効かつ使用可能であることを検証する必要があります。Webhookサーバーは、リクエストからのチャレンジをレスポンス内に含めなければなりません。そうしないと、ライセンスサーバーはそのリクエストを失敗としてマークし、Webhookを無効にします。何らかの理由でURLの検証が失敗したとサーバーが判断した場合、Webhookは無効になり、新しいイベントは送信されません。新しいURLが検証されている間、サーバーはこれらのイベントをキューに入れることもありません。
リクエスト
{ "type": "url_verification", "challenge": "" }
キー |
型 説明 |
|---|---|
type |
string |
送信されるリクエストのタイプ。リクエストがWebhookサーバーのURLの検証を試みる際は、これは常に |
challenge |
string | ランダムに生成されるチャレンジによって、Webhookサーバーから返されるレスポンスが、実際にライセンスサーバーからのリクエストに対するレスポンスであることを確認します。 |
レスポンス
{ "challenge": "" }
キー |
型 説明 |
|---|---|
challenge |
string | リクエスト内のチャレンジキーの値。ライセンスサーバーが、レスポンスが実際に元のリクエストに対するレスポンスであることを検証するために必要です。 |
イベントリクエスト ¶
各イベントには、送信を成功させるチャンスが3回与えられます。1回目のリトライは、リクエストが失敗したと判断された1分後に送信され、2回目のリトライは、1回目のリトライが失敗した5分後に送信されます。リクエストは、Webhookサーバーからの3xx HTTPレスポンスから、最大2回までリダイレクトすることができます。リクエストが2回よりも多くリダイレクトされた場合、下記のtoo_many_redirectsという失敗理由により失敗します。
送信中のリクエストのステートを示すのに役立つ特別なヘッダがいくつかあります。これらの特別なヘッダについて、以下の表で説明します。
ヘッダ |
説明 |
|---|---|
X-SideFX-Retry-Num |
イベントのリトライ数を示します。イベントの1回目のリトライの場合、このヘッダはリクエストに含まれません。 |
X-SideFX-Retry-Reason |
リトライの理由を示します。リクエストが失敗する様々な理由については、以下の表で説明しています。イベントの1回目のリトライの場合、このヘッダはリクエストに含まれません。 |
以下の表のように、リクエストが失敗する理由には様々なものがあります。
リトライの理由 |
説明 |
|---|---|
http_timeout |
以前タイムアウトしたHTTPリクエスト。 |
http_error |
以前の試行でエラーになったHTTPリクエスト。 |
too_many_redirects |
以前のリクエストが最大2回を越えてリダイレクトされました。 |
connection_failed |
以前の試行でWebhookサーバーに接続できませんでした。 |
ssl_error |
以前の試行でSSLエラーが発生しました。 |
unknown_error |
以前の試行でエラーが発生したが、sesinetdには失敗した理由が分からない、すべてのエラーをキャッチします。 |
ペイロード ¶
ライセンスサーバーからWebhookサーバーに送信される各リクエストは、以下と同じ構造になります。
リクエスト
{ "event": {}, "event_time": 000000, "event_id": "E100", "type": "event_callback", }
キー |
型 説明 |
|---|---|
event |
object | イベント固有の情報をすべて保持するオブジェクト。 |
event_time |
timestamp | イベントが発生したタイムスタンプ。タイムスタンプは、サーバーのエポックタイムで表現されます。 |
event_id |
string | 発生したイベントのID。各イベントには固有のIDがあり、それを使用してタイプを特定できます。 |
type |
string |
ライセンスサーバーからイベントリクエストを受信する時、この値は常に |
Webhookのステート ¶
Webhookのステートは、Webhookイベントを送信するための健全性および能力を示します。
ステータス |
説明 |
|---|---|
Active |
Webhookは動作しており、Webhookサーバーへのリクエストの90%以上が正常に応答しています。 |
Unstable |
Webhookは不安定な状態で動作しています。Webhookサーバーへのリクエストの90%から5%が成功しています。 |
Failed |
Webhookは正常に動作していません。Webhookサーバーへのリクエストの5%未満が成功しています。Webhookは無効になり、新しいイベントはWebhookサーバーに送信されません。Webhookサーバーが修復されたら、Webhookを手動で再度有効にする必要があります。Webhookを再度有効にするには、hkeyまたは公開APIを使用します。 |
Disabled |
Webhookは無効になっています。イベントはWebhookサーバーに送信されません。hkeyまたは公開APIを使用して、Webhookを手動で再度有効にする必要があります。 |
イベントに応答する ¶
システムがリクエストを成功とみなすには、Webhookサーバーがイベントに応答する必要があります。sesinetdが、送信に失敗したとみなされるイベントを多数受信した場合、Webhookは無効になります。各リクエストには、失敗するまでに3秒の応答時間が与えられ、その時間の経過後は、ここで説明した理由http_timeoutにより失敗します。sesinetdが、リクエストに対してWebhookサーバーから200 HTTPレスポンスを受信した場合、リクエストは成功とみなされます。
Note
sesinetdは、送信に失敗したイベントや、WebhookがDisabledまたはFailedステートの時に発生したイベントをキャッシュ化しません。これらのイベントは失われ、取得する方法はありません。
リトライをオフにする ¶
Webhookサーバーがイベントに追いつくのに苦労している場合や、sesinetdにイベント送信のリトライをしてほしくない場合は、特別なHTTPヘッダによってそれを指定することができます。リトライをオフにするには、次の特別なヘッダを200 HTTP以外のレスポンスに含めます。
X-Slack-No-Retry: 1
このヘッダは、この特定のイベントをリトライしないようsesinetdに指示します。他のすべてのイベントは何も影響を受けず、必要に応じてリトライされます。
スロットリング ¶
現在、Webhookはスロットリングをサポートしていません。
レート制限 ¶
重要なのは、追いつくことのできないイベントでサーバーをフラッディングさせないことです。
イベントは、60分あたり最大30,000のリクエストを送信します。sesinetdがその最大値に達すると、sesinetdはその時間、サーバーへの新しいイベントの送信を停止します。その間サーバーはレート制限され、sesinetdはrate_limitedイベントを毎分送信します。
{ "type": "rate_limited", "minute_rate_limited": 1691771520 }
キー |
型 説明 | |
|---|---|---|
minute_rate_limited |
Integer |
サーバーがレート制限イベントを開始した分を示す、丸めたエポックタイム。 |
type |
string |
レート制限イベントを受信する時、タイプは |
Webhookを編集する ¶
すべてのユーザがWebhookおよびイベントのサブスクリプションを表示することができます。Webhook URLおよびサブスクリプションを編集することができるのは、管理者権限を持つユーザのみです。