Webhook プログラミングガイド

Webhookを使用すると、ミニアプリで何らかのイベントが発生した時、例えば、レコードが追加された時などに、通知を受け取ることができます。

Platioは、それらのイベントが発生した時に、HTTPリクエストを使用して通知を送りますので、お客様側でHTTPリクエストを受け取れるサーバーなどを用意する必要があります。ミニアプリでイベントが発生すると、そのサーバーにイベントに関する情報が送られます。

このドキュメントでは、Webhookを使って、どのように通知を受け取るのかについて説明します。このドキュメントは、Platioと、Platio APIの基本的な部分に慣れ親しんでいることを前提としています。もし、Platio APIに慣れていない場合、Platio API プログラミングガイドに一通り目を通してください。また、このドキュメントでは、PHP、Node.js、ASPのような特定の環境で、どのように通知を処理するかについては説明しません。個々の環境については、それぞれのドキュメントを参照してください。

概要

現在、Platioは、新しいレコードが追加されたとき、既存のレコードが更新されたとき、既存のレコードが削除された時に通知を送ることができます。これらのイベントは、お客様のサーバーにリクエストを送ることで通知されます。

デフォルトでは、通知はPOSTを使用して送られます。POSTされるリクエストの本体は、イベントに関連付けられたレコードを含むJSONデータです。例えば、新しいレコードが追加された場合には、リクエスト本体は以下のようになります。

{
  "applicationId": "pkyfjjjmlyffnlgeb5oh2eqs2aa",
  "collectionId": "tf71dbb9",
  "event": "insertRecord",
  "record": {
    "id": "rint7fzi2dnhdbezupqgla23eby",
    "createdAt": "2017-07-07T01:45:01.612Z",
    "updatedAt": "2017-07-07T01:45:01.612Z",
    "createdBy": {
      "id": "uf598c3f",
      "name": "user1"
    },
    "updatedBy": {
      "id": "uf598c3f",
      "name": "user1"
    },
    "values": {
      "c002c2c0": {
        "type": "String",
        "value": "Jeff Scott"
      },
      "c915a0bc": {
        "type": "Number",
        "value": 40
      }
    },
    "hash": "cafe99c53ad2e430066d861f40e098a1c02a297a",
    "timestamp": "2017-07-07T01:45:01.624Z"
  }
}

applicationIdとcollectionIdは、それぞれ、アプリケーションとコレクションのIDを表します。eventは、insertRecord、updateRecord、deleteRecordのいずれかになります。名前からわかるように、それぞれ、レコードが作成された、更新された、削除されたことを意味します。

recordプロパティは、対象のレコードを表します。詳細については、Platio API プログラミングガイドを参照してください。レコードが削除されたときには、recordプロパティは、空のvaluesを持つことに注意してください。例えば、以下のようになります。

{
  "applicationId": "pkyfjjjmlyffnlgeb5oh2eqs2aa",
  "collectionId": "tf71dbb9",
  "event": "deleteRecord",
  "record": {
    "id": "rint7fzi2dnhdbezupqgla23eby",
    "createdAt": "2017-07-07T01:45:01.612Z",
    "updatedAt": "2017-07-07T01:45:01.612Z",
    "deletedAt": "2017-07-07T01:45:01.612Z",
    "createdBy": {
      "id": "uf598c3f",
      "name": "user1"
    },
    "updatedBy": {
      "id": "uf598c3f",
      "name": "user1"
    },
    "deletedBy": {
      "id": "uf598c3f",
      "name": "user1"
    },
    "values": {
    },
    "hash": "cafe99c53ad2e430066d861f40e098a1c02a297a",
    "timestamp": "2017-07-07T01:45:01.624Z"
  }
}

リクエストのContent-Typeは、application/jsonになります。

リクエスト本体の変換

あらかじめルールを設定しておくことにより、リクエストの本体を変換してサーバーに送ることができます。変換ルールは、Platio式で指定します。Platio式にはレコードが引数として渡されます。

例えば、以下のようなPlatio式を指定します。

{
    name: c002c2c0,
    age: c915a0bc
}

すると、上記のリクスト本体は以下のように変換されてサーバーに送られます。

{
    "name": "Jeff Scott",
    "age": 40
}

変換後のJSONは、Object型である必要があります。

リクエストの条件

レコードが特定の条件を満たした場合だけ、リクエストをサーバーに送ることができます。条件は、Platio式で指定します。Platio式にはレコードが引数として渡されます。

例えば、c915a0bc >= 40という条件を指定すると、このカラムの値が40以上の場合にのみリクエストが送られます。

GETでの通知

Webhookの設定で、GETを使用するようにした場合、変換後のJSONをクエリパラメーターとして通知します。例えば、変換後に上記のようなJSONになった場合、通知先のURLが、http://www.example.org/testだとすると、http://www.example.org/test?name=Jeff%20Scott&age=40にGETリクエストが送られます。

GETで通知する場合、変換用のPlatio式の指定は必須で、変換後のJSONは、値が全て文字列、数値、真偽値のObject型である必要があります。

フォームデータでの通知

Webhookの設定で、POSTを使用するようにし、さらにフォームデータを使うように指定すると、JSONの代わりにフォームデータとしてサーバーに通知が送られます。例えば、変換後に上記のようなJSONになった場合、以下のような本文のリクエストが送られます。

name=Jeff%20Scott&age=40

この場合、リクエストのContent-Typeは、application/x-www-form-urlencodedになります。また、GETを使用する場合と同様、変換用のPlatio式の指定は必須で、変換後のJSONは、値が全て文字列、数値、真偽値のObject型である必要があります。

サーバーの実装

Webhookの呼び出し先のサーバーを実装する時には、いくつか気をつける点があります。まず、上記の通り、POSTリクエストを処理できる必要があります。

通知を処理したときには、2xxレスポンスを返します。典型的には200レスポンスを返しますが、その他の任意の2xxレスポンスを返すことができます。2xx以外のレスポンスを返すと、エラーとして処理されます。リダイレクトはある程度まで処理されます。

レスポンスの本体は、空か、少なくとも短い必要があります。いずれにしてもレスポンス本体は無視されます。レスポンス本体が大きすぎるとエラーとして扱われる事があります。

サーバーが3秒以内にレスポンスを返さないと、エラーとして扱われます。この3秒には、サーバーに接続する時間、リクエストを送る時間、レスポンスを受け取る時間が含まれます。サーバーでは、通知を素早く処理するようにしてください。複雑な処理をしたい場合には、レスポンスを返した後で処理を継続するか、何らかのキューに通知を入れて、後で処理してください。

再試行

サーバーに接続できなかったり、エラーレスポンスを受け取ったり、レスポンスを時間内に受け取れなかった場合には、数秒の待ち時間を挟んで、全体で最大3回まで、再試行されます。再試行しても失敗する場合、エラーとして扱われます。

モードとエラー処理

Webhookには２つのモードがあります。一つ目のモードは順序保証モードで、もう一つのモードはクイックモードです。

順序保証モード

順序保証モードでは、全てのイベントが、イベントが起きた順番で通知されます。例えば、レコードを追加し、更新し、削除した場合、必ずこの順番で通知されます。別のレコードの関するイベントの順番も保持されます。また、一つ前のイベントの処理が完全に終わるまで、次のイベントに関する通知は行われません。

このモードでは、エラーが発生すると、直ちにWebhookが無効になります。これは、イベントが間違った順番で届かないようにするためです。Webhookが無効になった後のイベントに関しての通知は破棄されますので、再度Webhookを有効にすると、有効にした後のイベントのみが送られます。

このモードは、Platioと別のシステムを連携する場合などにお使いいただけます。

クイックモード

クイックモードでは、通知の順番は保証されません。同じレコードに関する通知が、削除、作成、更新の順番で通知されることもあります。また、複数の通知が同時に行われることもあります。

このモードでは、エラーが発生しても、引き続き、後続のイベントに関する通知が送られます。このため、ネットワークエラーやサーバーエラーが発生しても、自動で復旧することができます。ただし、クイックモードでも、エラーがある程度以上発生すると、Webhookが無効になります。Webhookが無効になった後のイベントに関しての通知は破棄されますので、再度Webhookを有効にすると、有効にした後のイベントのみが送られます。

このモードは、例えば、イベントをSlackに通知したり、メールで送るなどの、軽い連携でお使いいただけます。

ログ

Platioは、通知を送るとログを残します。エラーが発生した場合には、エラーの内容もログに残されます。Platio Studioで、このログを確認したりダウンロードすることができます。Webhookが上手く動かない場合、ログを確認してください。ログは2週間保持されます。

レコードと添付ファイル

Webhookで通知されたレコードが使用している添付ファイルを取得するときには、注意が必要です。添付ファイルは、レコードとは別にアップロードされるため、Webhookが呼び出された時点で、レコードが使用している添付ファイルがまだ存在しない可能性があります。そのような場合には、しばらく間を置いて再試行してください。

制限

一定時間内に呼び出せるWebhookの回数には、制限があります。以下が現在の制限ですが、これらは変更される可能性があります。これらの制限は、アプリケーション単位で適用されます。

Webhook	Standard, Premiumプランの制限	Enterpriseプランの制限
クイックモードでの呼び出し	1時間あたり5,000呼び出し	1時間あたり10,000呼び出し