Link Search Menu Expand Document

Webhook API

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

Table of contents

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

リクエストの仕様

HTTPメソッド

POST

タイムアウト

10秒

リトライ

最大5回までリトライを行います。リトライの間隔は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アドレス

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

  • 54.173.229.200
  • 54.175.230.252

リクエストボディ

下位の形式の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_rejected チケットが差し戻された
ticket_completed チケットが完了した
ticket_withdrawn チケットが取り下げられた
ticket_deleted チケットが削除された

ping

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

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

ticket_*

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

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

Copyright © 2021 kickflow, Inc.