メインコンテンツへスキップ

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サーバをご用意ください。

{
    "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 Zendesk