Callback

루니버스 API 중 비동기로 처리되는 API들의 경우, 해당 요청의 처리가 완료된 후 루니버스 서버에서 Callback을 호출하도록 설정 할 수 있습니다. 이 페이지에서는 Callback을 어떻게 구현하고, 설정하는지에 대해 설명합니다.

Callback이란?

일반적인 구현 방식에서 콜백은 특정 이벤트가 발생하거나 특정 작업이 완료된 후에 실행되는 함수를 의미합니다. 루니버스 API에서 콜백의 목적은 루니버스 서버에서 시간이 오래걸리는 배치성 처리나 블록체인을 통한 비동기 작업을 완료한 후 클라이언트 측에 다음 작업을 수행하기 위한 신호를 주는 것에 있습니다.


Callback을 사용하려면 어떤 작업이 필요한가요?

콜백을 사용하려면 클라이언트 측, 즉 루니버스 서버를 호출하는 사용자 측에서 루니버스 서버가 요청의 처리 결과를 전달할 수 있는 endpoint를 구현하여 제공해야 합니다. Endpoint 구현에 관한 요구사항은 다음과 같습니다.

  1. 접근성 요구사항
    1. Public 네트워크를 통해 누구나 접근 가능한 endpoint여야 합니다. 도메인 및 Path 구성에 대한 별도의 제약사항은 없습니다.
  2. 인터페이스 요구사항
    1. POST 방식의 REST API 호출을 처리할 수 있어야 합니다. (루니버스 서버는 콜백 파라미터가 포함된 요청의 처리가 완료된 후 해당 URL로 POST API를 호출합니다.)
    2. 콜백 메시지를 수신한 후 응답으로 200 OK 또는 201 CREATED의 HTTP 상태코드를 응답해야 합니다. 만약 일시적인 서버 장애 등으로 인해 콜백을 수신하는 서버로부터 4XX 또는 5XX 에러코드가 응답되는 경우, 루니버스 서버는 콜백 메시지 송신을 최대 3번까지 재시도합니다.
    3. 콜백 메시지의 Body에 포함되는 내용은, 원본 요청이 어떤 요청이었는지에 따라 다릅니다. 관련 스펙은 콜백을 허용하는 각 API 명세 페이지에서 확인하세요.

Callback 동작 Flow