Webhookの仕様

Webhookの仕様

Webhookとは?

Webhookとは、「車両が特定の訪問先に到着した」などのイベントが発生した際に、その情報をリアルタイムに指定されたURL(サーバー)へHTTP POSTする機能です。外部システムとの連携などに利用できます。

対応しているイベント種別

Cariotでは、様々なイベントを検知しますが、現在、全てのイベント種別がWebhookの送信対象としてサポートされてはいません。

現在、サポートされているイベントの種類は以下の3種類です。

拠点への到着
拠点からの出発
拠点にもうすぐ到着=到着予定時刻(推定)が現在時刻から●●分以内になった時

Webhookの管理(登録・変更・削除)方法

Webhookを利用するためには、Webhookの設定情報を登録する必要があります。

Webhookは、Salesforce組織外のシステムとAPIで連携するための仕組みであるため、Salesforce(Cariotパッケージ)上で管理画面を提供していません。

したがって、Webhookの設定自体も、Cariot APIで管理する必要があります。

Webhookの一覧を取得: GET /api/webhooks
Webhookを新規に登録: POST /api/webhooks
Webhook の登録内容を変更: PUT /api/webhooks/{webhook_id}
Webhookを削除: DELETE /api/webhooks/{webhook_id}

APIの構文についてはAPIドキュメント( https://api-doc.cariot.jp )を参照してください。

イベント種別 ( event_types )には、以下が指定可能です。

拠点への到着geo_point_enter
拠点からの出発geo_point_leave
拠点にもうすぐ到着geo_point_arriving

Webhookメッセージを受け取る外部サーバの前提条件

Cariotサーバから外部サーバへ送信するデータはHTTPS通信になります。そのため、外部サーバ側で、SSLサーバ証明書の登録が必要になります。

また、外部サーバは、インターネット/DMZに公開している必要があります。

Cariotサーバから外部サーバへのPOST時、リクエストの認証の手段として、Webhook登録時にHTTPセキュリティヘッダ(通常Authorizationヘッダ)を指定することが可能です。ヘッダの他、Cariotサーバの送信元のIPアドレスは固定となるため、外部サーバ側でIPアドレス制限を行うこともできます(IPアドレスについては個別にお問い合わせください)

Webhookメッセージのフォーマット

Cariotサーバから外部サーバへは、以下のようなフォーマットのメッセージをPOSTで送信します。

このフォーマットのメッセージをエラーなく受信できるようなAPIサーバをご用意ください。

code
Copied!
{
"events": [
{
"device_sn": "12345",
"event_type": "geo_point_arriving",
"timestamp": 1475659461000,
"latitude": 35.123,
"longitude": 135.456,
"speed": 111.111,
"direction": 111.111,
"webhook": {
"id": "aaaaa",
"name": "aaaaa",
"description": "aaaaa"
},
"geo_point": {
"id": "aaa",
"name": "aaa",
"latitude": 35.111,
"longitude": 135.111,
"radius": 200,
"arrive_within": 5,
"on_leave": true,
"on_enter": true,
"on_arriving": false,
"strict_order": false
},
"geo_route": {
"id": "aaa",
"name": "aaa"
}
"estimated_duration": 123
}
]
}

events
検知されたイベントの1件1件のリストです。
リスト形式(複数)になっていることからわかるように、時間的に近いタイミングで複数のイベントが検知された場合は、1回のHTTP POSTに複数のイベントの内容をまとめて送信することがあります。
events > device_sn
イベントが発生したデバイスのシリアルです。
events > event_type
発生したイベントの種類です。
events > timestamp
イベントが発生した時刻です。Cariotサーバ側の検出時刻ではなく、デバイス側から申告された時刻になります。
events > latitude|longitude
イベントが発生した時の場所(緯度、経度)です。
events > speed
イベントが発生した時の車両の速度(km/h)です。
events > directions
イベントが発生した時の車両の向き(0〜359。真北を0°として時計回りの角度)
events > webhook
イベント送信の契機となったWebhookの設定情報です。
events > geo_point
イベントが発生した拠点の登録情報です。
events > geo_route
イベントが発生したルート(拠点の親)の登録情報です。
events > estimated_duration
発生したイベントが「もうすぐ到着(geo_point_arriving)」の時のみ
目的地までの到着予定時間(秒)です。
Powered by Helpfeel