Fleet API Webhook Overview

개요

Fleet API Webhook은 실시간으로 발생하는 차량의 데이터를 고객이 원하는 Endpoint로 수신할 수 있도록 하는 기능입니다.

Webhook의 종류

다음과 같은 종류의 Webhook을 제공합니다.

• 주기 데이터 : 차량에서 주기적으로 발생하는 이벤트에 대한 정보 (차량의 현재 속도, 위치 등)
• 이벤트 데이터 : 특정 트리거를 통해 발생하는 차량의 이벤트 (문열림, 충격 감지 등)

Pre-requisite

Webhook을 사용하기 위해서는 다음과 같은 준비가 필요합니다.

1. Pleos Playground를 통해 Client ID와 Client Secret, Project ID를 발급받습니다.
2. Pleos Fleet에서 Webhook을 등록해야 합니다.

Webhook 등록하기

Getting started의 Webhook 시작하기 섹션을 참고하여 Webhook을 등록하세요.

Webhook의 동작 방식

Fleet API Webhook은 차량 또는 Pleos Fleet에서 이벤트가 발생했을 때, 사전에 등록된 엔드포인트로 실시간 HTTP 요청을 전송하는 방식으로 동작합니다.

1. Webhook 이벤트 구독
   Fleet API를 통해 특정 차량 또는 FMS 이벤트에 대한 Webhook 구독이 등록됩니다.

2. 이벤트 발생
   차량의 상태 변화(예: 문열림, 충격 감지 등) 또는 FMS 이벤트(예: 트립 생성, 차량 정보 수정 등)가 발생하면, Fleet API는 해당 이벤트를 Webhook을 통해 전송합니다.

3. HTTP 요청 전송
   Fleet API는 사전에 등록된 엔드포인트로 이벤트 데이터를 포함한 HTTP 요청을 보냅니다.

4. Callback response 처리
   엔드포인트에서 유효한 응답(예: 200 OK)을 반환하면 요청이 성공으로 처리됩니다.
   응답이 유효하지 않거나 일정 시간 내에 응답을 받지 못하면 요청이 실패로 간주되며, 최대 재시도 횟수만큼 재시도합니다.

Custom Header의 설정

Webhook을 수신하는 사용자의 endpoint에서 인증 등 Header 정보의 추가가 필요한 경우, 사용자가 Custom Header를 직접 설정할 수 있습니다.

Custom Header 등록하기

Pleos Fleet을 통해 Webhook을 등록할 때, 사용자는 다음과 같은 방식으로 Custom Header를 설정할 수 있습니다.

1. Pleos Fleet에서 Webhook 관리 페이지로 이동
   Webhook을 새로 생성하거나 기존 Webhook을 수정할 수 있습니다.

2. 필요한 Custom Header 등록
   Webhook 요청 시 포함할 헤더를 Key-Value 형태로 입력합니다.

3. Webhook 최종 등록
   설정이 완료되면 Webhook을 통한 요청 전송 시 지정된 Header가 포함되어 전송됩니다.

Custom Header 등록 예시

Custom Header Name	Value	설명
Authorization	Bearer your_token_here	API 인증을 위한 Bearer Token
X-Custom-Header	custom_value	추가적인 사용자 정의 헤더 값

이를 통해 사용자의 endpoint에서 인증 및 추가적인 데이터 처리가 가능하도록 구성할 수 있습니다.

기타

[Webhook 사용 주의사항]

Webhook의 Response를 Fleet API에서 지원하는 형태로 제공해야 정상적인 사용이 가능합니다. Fleet API Webhook callback response를 참고하여 Callback의 응답을 작성해주세요.