Webhook API

1. はじめに

SmartBeatコンソールでWebhook通知を設定した場合、以下の仕様のとおりに通知のリクエストが送信されます。仕様にそって受付サーバを用意するか、あるいは Zapier のようなサービスを利用することで、任意の通知先(チャットサービスなど)でイベントを受け取ることができます。

2. Webhook API

2-1. Verification

通知先URLの疎通確認

 

リクエスト例
POST /my_webhook HTTP/1.1

...
Content-Type: application/json; charset=utf-8
X-Hub-Signature: sha1=2fd5ed887e3d87e3cd86e947864c8f1ecedde71c

{
    "event": "verification",
    "application": {
        "name": "MyApp",
        "platform": "iOS",
        "status": "Development"
    }
}

 

リクエスト情報
フォーマット
JSON
メソッド
POST

 

リクエストヘッダ
Content-Type
コンテンツタイプ

"application/json; charset=utf-8"が設定されます。

X-Hub-Signature
メッセージの署名(HMAC-SHA1)

リクエストボディからSHA-1により生成されたハッシュ値です。キーとしてAPI Token(SmartBeatコンソールのアプリケーションの一般設定で確認できます)が使用されます。受付サーバでリクエストボディからAPI TokenをキーとしてSHA-1によりハッシュ値を生成し、このヘッダの内容と照合することで、受け取ったメッセージが正しくSmartBeatのサーバから送られたものであることが確認できます。

 

リクエストボディ

JSON形式で送信されます。

event
イベントの種類

"verification"が設定されます。

application/name
アプリケーション名

SmartBeatコンソールでアプリケーション名として登録したものが設定されます。

application/platform
アプリケーションのプラットフォーム

iOS | Android | Web

application/status
アプリケーションのステータス

Development | Production

 

レスポンスステータス
200
成功

有効なURLと判断され、その後SmartBeatコンソール上で「更新する」をクリックすると設定が更新されます。

200以外
エラー

無効なURLと判断され、設定に反映することはできません。

2-2. New error

新規エラー発生通知

 

リクエスト例
POST /my_webhook HTTP/1.1

...
Content-Type: application/json; charset=utf-8
X-Hub-Signature: sha1=c2b0bf96e202300fb0fe36f817518259d9acdbe1

{
    "event": "new_error",
    "application": {
        "name": "MyApp",
        "platform": "iOS",
        "status": "Development"
    },
    "error": {
        "url": "https://dash.smrtbeat.com/console/error_detail?a=1&e=123456789",
        "count": 1,
        "type": "crash",
        "message": "NSInvalidArgumentException: -[ViewController incorrectSelector]: ...",
        "location": "main.m:main() : 16",
        "application_version": "1.1",
        "os_version": "10.3.1",
        "device": "iPhone 7 [iPhone9,1]",
        "stack_trace": "0 CoreFoundation 0x000000018e83afd8 __exceptionPreprocess() + 120\n..."
    }
}

 

リクエスト情報
フォーマット
JSON
メソッド
POST

 

リクエストヘッダ
Content-Type
コンテンツタイプ

"application/json; charset=utf-8"が設定されます。

X-Hub-Signature
メッセージの署名(HMAC-SHA1)

リクエストボディからSHA-1により生成されたハッシュ値です。キーとしてAPI Token(SmartBeatコンソールのアプリケーションの一般設定で確認できます)が使用されます。受付サーバでリクエストボディからAPI TokenをキーとしてSHA-1によりハッシュ値を生成し、このヘッダの内容と照合することで、受け取ったメッセージが正しくSmartBeatのサーバから送られたものであることが確認できます。

 

リクエストボディ

JSON形式で送信されます。

event
イベントの種類

"new_error"が設定されます。

application/name
アプリケーション名

SmartBeatコンソールでアプリケーション名として登録したものが設定されます。

application/platform
アプリケーションのプラットフォーム

iOS | Android | Web

application/status
アプリケーションのステータス

Development | Production

error/url
エラー詳細ページのURL
error/count
エラー発生回数
error/type
エラー種別

crash | signal | exception

error/message
エラーメッセージ
error/location
エラー発生箇所
error/application_version
エラーが発生したアプリバージョン
error/os_version
エラーが発生したOSバージョン
error/device
エラーが発生した端末のモデル名

※iOS, Androidのみ

error/browser
エラーが発生したブラウザ

※Webのみ

error/stack_trace
エラー発生時のスタックトレース

 

レスポンスステータス
2xx
成功

200番台は全て正常に処理したものとして扱われますが、通常は200を返してください。

404
見つからない

無効なURLと判断され、以降の通知は停止します。通知を再開するためには、SmartBeatコンソールでWebhook通知のURLを再設定してください。

4xx(404以外)、5xx
エラー

1度リトライ(10秒後あるいはRetry-Afterで指定した時間の後)が行われます。

上記以外
想定外

想定外のレスポンスとして無視されます。

 

レスポンスヘッダ

以下のレスポンスヘッダを返すことで、SmartBeatからのAPIアクセスの頻度を制御できます。

Retry-After
Optional
リトライ時間

エラーレスポンスのときのリトライまでの時間を、相対的な秒数あるいは絶対的な時刻(HTTP-date)で指定できます。

最大300秒先まで指定できます。それ以上を指定した場合はリトライされません。

4xx(404以外)または5xxのステータスとともに使用してください。それ以外の場合は設定が無視されます。

X-RateLimit-Remaining
Optional
APIアクセス残り回数

0に設定した場合に以降のAPIアクセスが制限されます。制限中に発生した通知は破棄されます。

4xx(404以外)または5xxのステータスの場合で、かつX-RateLimit-Resetヘッダに制限を解除する時刻を指定した場合のみ機能します。それ以外の場合は設定が無視されます。

X-RateLimit-Reset
Optional
APIアクセスリセット時刻

APIアクセスの制限を解除する時刻を指定します。指定した時刻より後に発生した通知から送信が再開されます。

最大24時間先まで指定できます。それ以上を指定した場合は24時間後に制限が解除されます。

4xx(404以外)または5xxのステータスの場合で、かつX-RateLimit-Remainingヘッダに0を設定した場合のみ機能します。それ以外の場合は設定が無視されます。