Webhook API

kickflowで発生したイベントを任意のエンドポイントへ通知

Table of contents

  1. リクエストの仕様
    1. HTTPメソッド
    2. タイムアウト
    3. リトライ
    4. ヘッダー
    5. IPアドレス
    6. リクエストボディ
  2. レスポンスの仕様
  3. イベントタイプの一覧
    1. ping
    2. ticket_*
    3. comment_*
  4. 注意事項

リクエストの仕様

HTTPメソッド

POST

タイムアウト

10秒

リトライ

最大10回までリトライを行います。リトライの間隔はExponential Backoffによって調整されます。

ヘッダー

下記のヘッダーを含みます。

ヘッダー 説明
Content-Type application/json
User-Agent kickflow-Hookshot/v1
X-Kickflow-Delivery イベント固有のUUID
X-Kickflow-Signature 改ざんを防止するためのシグネチャ（Webhook設定時にシークレットを登録した場合のみ）

X-Kickflow-Signatureは、ペイロードのJSON文字列に対してWebhook設定のシークレットをキーとしてHMAC-SHA256を計算し、先頭にsha256=を付与した文字列になります。

X-Kickflow-Signature: sha256=709e8de4bbf818bbbd9ee7f52866322dffcf7efea31d7aec5f397468cc11df18

Webhookを受け取るエンドポイント側では、受信したペイロードとシークレットからHMAC-SHA256を計算し、これをX-Kickflow-Signatureの値と比較することで正規のリクエストかどうかを判定してください。

IPアドレス

Webhookの送信元IPアドレスは以下になります。このIPアドレスは将来予告の上で変更になる可能性があります。

  • 173.44.50.7

2023年6月1日から以下のIPアドレスがWebhookの送信元IPアドレスに追加されます。 ファイアウォールなどでアクセス制限している場合、新しいIPアドレスの追加をお願いします。

  • 52.5.38.201
  • 52.7.247.138

リクエストボディ

下位の形式のJSONとなります。data以下はイベントのタイプごとに異なります。例えば、チケット承認イベントのボディは以下のようになります。

{
  "eventType": "ticket_approved",
  "tenant": {
    "id": "string",
    "publicId": "string",
    "name": "string"
    ...
  },
  "user": {
    "id": "string",
    "publicId": 1,
    "firstName": "string",
    "lastName": "string",
    "fullName": "string",
    "email": "string",
    ...
  },
  "data": {
    "ticket": {
      "id": "string",
      "publicId": 1,
      "title": "string",
      ...
    }
  }
}

eventTypeはイベントタイプを表す文字列、tenantは企業情報、userはイベントを発生させたユーザー情報です。これらはすべてのイベントタイプのペイロードに含まれます。

dataはイベントタイプ固有のペイロードです。data以下の属性はイベントタイプごとに異なります。

レスポンスの仕様

Webhookを受け取るエンドポイントを作成する際には、以下の要件を満たしてください。

  • HTTPステータスコード200を返却してください。kickflowはレスポンスボディを見ないため、レスポンスボディは空で構いません。
    • 400番台、500番台だけでなく、300番台（リダイレクト）を返した場合もエラーとみなします。
  • 10秒以内にレスポンスを返却するようにしてください。これを過ぎるとタイムアウトします。
  • リクエストがタイムアウトした場合、同じイベントのリクエストが2回送信されることがありますのでご注意ください。同じイベントのリクエストにはX-Kickflow-Deliveryヘッダーに同じ値が入っておりますので、こちらをチェックして判別してください。

イベントタイプの一覧

イベントタイプ 説明
ping Webhook作成または編集時に発生する特殊なイベント
ticket_created チケットが作成された
ticket_updated チケットが編集された
ticket_opened チケットが申請された
ticket_approved チケットが承認された（承認・差し戻しステップ）
ticket_confirmed チケットが確認された（回覧ステップ）
ticket_rejected チケットが差し戻された
ticket_denied チケットが却下された
ticket_completed チケットが完了した
ticket_withdrawn チケットが取り下げられた
ticket_archived チケットがアーカイブされた
comment_created コメントが作成された
comment_updated コメントが編集/削除された

ping

Webhookの設定を作成または編集したときに、kickflowは登録されたエンドポイントに対してpingイベントを送信します。正しくWebhookの設定ができているか確認するのに使用してください。

// 例: pingイベントのペイロード
{
  "eventType": "ping",
  "tenant": {
    ...
  },
  "user": {
    ...
  },
  "data": {
    "message": "ping"
  }
}

ticket_*

チケット関連のイベントには、チケットの詳細データが含まれます。チケットのスキーマは、 チケットを一件取得するAPI のレスポンスと同じです。

// 例: チケット作成イベントのペイロード
{
  "eventType": "ticket_created",
  "tenant": {
    ...
  },
  "user": {
    ...
  },
  "data": {
    "ticket": {
      ...
    }
  }
}

comment_*

コメント関連のイベントには、コメントの詳細データが含まれます。コメントのスキーマは、 data.comment部がコメントを取得API のレスポンスと同じ、data.ticket部がチケット一覧を取得API の1要素分のレスポンスと同じです。

// 例: コメント作成イベントのペイロード
{
  "eventType": "comment_created",
  "tenant": {
    ...
  },
  "user": {
    ...
  },
  "data": {
    "comment": {
      ...
    },
    "ticket": {
      ...
    }
  }
}

注意事項

  • Webhookは大量のリクエストを送信するために複数のサーバーに分散して処理されます。こうした背景から前のリクエストが送信完了してから後続のリクエストを送信するといった制御を行わないため、イベントの発生順序とリクエストが到達する順序が稀に前後する場合があります。Webhook受信時にチケットを外部のデータベースへ登録している場合、ペイロードに含まれるチケットのupdatedAtを確認し、より新しいチケット情報の場合のみ上書き処理を行うようにしてください。
  • 1週間失敗し続けているWebhoookは自動的に無効化され、以降リクエストが送信されなくなります。

Copyright © 2021 kickflow, Inc.