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)으로 지정이 가능합니다.

최대120초 앞에까지 지정이 가능합니다. 그 이상을 지정하는 경우에는120초 후에 리트라이가 진행됩니다.

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으로 설정할 때만 작동합니다. 그외에는 설정이 무시됩니다.