본문으로 건너뛰기

웹훅 (Webhooks)

웹훅을 사용하면 메시지 및 그룹 처리 상태, 팩스 수신과 같은 특정 이벤트가 발생했을 때 실시간으로 알림을 받을 수 있습니다.

Webhook 종류​

현재 솔라피에서 지원되는 웹훅 이벤트는 세 가지입니다.

  • 메시지 리포트: 개별 메시지 처리 완료 시
  • 그룹 리포트: 그룹 내 모든 메시지 처리 완료 시
  • 팩스 수신: 팩스 수신 완료 시

호출 및 응답 처리​

호출 시점​

각 이벤트는 처리가 완료되었을 때 한 번씩 설정된 URL로 호출됩니다.

  • 메시지 리포트: 메시지 건 별 처리가 완료될 때마다 호출됩니다.
  • 그룹 리포트: 그룹에 속한 모든 메시지의 처리가 완료되었을 때 호출됩니다.
  • 팩스 수신: 팩스가 정상적으로 수신되었을 때 호출됩니다.

구현 가이드​

웹훅 이벤트 수신 시, 서버는 HTTP Status Code 200 을 반환해야 합니다. 응답 내용과 관계없이 200 코드를 받으면 저희 시스템은 전달이 성공했다고 판단하며, 그렇지 않을 경우 재시도를 시작합니다.


재시도 정책​

이벤트 전달에 실패하면 총 7번의 추가 재시도 가 이루어집니다(최초 시도 포함 총 8회). 재시도 간격은 실패할 때마다 두 배씩 증가하며, 첫 재시도는 15분 후에 시작됩니다.

  • 1차 재시도: 최초 실패 후 15분 뒤
  • 2차 재시도: 1차 실패 후 30분 뒤
  • 3차 재시도: 2차 실패 후 60분 뒤
  • ...이와 같이 간격이 두 배로 늘어납니다.
웹훅 비활성화

총 8번의 시도에도 불구하고 이벤트 전달에 모두 실패하면, 해당 웹훅 URL은 비활성화 상태로 변경되며 더 이상 이벤트를 전달하지 않습니다.


데이터 형식 (POST)​

모든 웹훅 이벤트는 설정된 URL에 HTTP POST 요청으로 전달됩니다. 각 이벤트별 데이터 형식은 아래 예시를 참고하세요.

메시지 리포트 예시 보기
[
  {
    "messageId": "M4V202212291118233WFNUDAXMX1A001",
    "groupId": "G4V20221229111823FFGLDPAQEP3FF86",
    "type": "ATA",
    "to": "01000000001",
    "from": "029302266",
    "statusCode": "4000",
    "statusMessage": "수신 완료",
    "dateProcessed": "2022-12-29T02:18:40.713Z",
    "dateReported": "2022-12-29T02:18:45.000Z",
    "dateReceived": "2022-12-29T02:18:44.000Z",
    "networkCode": "90901",
    "customFields": {
      "name": "홍길동"
    }
  },
  {
    "messageId": "M4V202212291118233WFNUDAXMX1A002",
    "groupId": "G4V20221229111823FFGLDPAQEP3FF86",
    "type": "ATA",
    "to": "01000000002",
    "from": "029302266",
    "statusCode": "4000",
    "statusMessage": "수신 완료",
    "dateProcessed": "2022-12-29T02:18:40.813Z",
    "dateReported": "2022-12-29T02:18:45.000Z",
    "dateReceived": "2022-12-29T02:18:44.000Z",
    "networkCode": "90901",
    "customFields": {
      "name": "고길동"
    }
  }
]
그룹 리포트 예시 보기
[
  {
    "count": {
      "total": 1,
      "sentTotal": 1,
      "sentFailed": 0,
      "sentSuccess": 1,
      "sentPending": 0,
      "sentReplacement": 0,
      "refund": 0,
      "registeredFailed": 0,
      "registeredSuccess": 1
    },
    "countForCharge": {
      "sms": {},
      "lms": {},
      "mms": {},
      "ata": {
        "82": 1
      },
      "cta": {},
      "cti": {},
      "nsa": {},
      "rcs_sms": {},
      "rcs_lms": {},
      "rcs_mms": {},
      "rcs_tpl": {}
    },
    "balance": {
      "requested": 8,
      "replacement": 0,
      "refund": 0,
      "sum": 8
    },
    "point": {
      "requested": 0,
      "replacement": 0,
      "refund": 0,
      "sum": 0
    },
    "app": {
      "profit": {
        "sms": 0,
        "lms": 0,
        "mms": 0,
        "ata": 0,
        "cta": 0,
        "cti": 0,
        "nsa": 0,
        "rcs_sms": 0,
        "rcs_lms": 0,
        "rcs_mms": 0,
        "rcs_tpl": 0
      },
      "appId": null,
      "version": null
    },
    "serviceMethod": "MT",
    "sdkVersion": null,
    "osPlatform": null,
    "log": [
      {
        "createAt": "2022-12-29T02:16:12.936Z",
        "message": "[14.36.11.105] 메시지 그룹이 생성되었습니다."
      },
      {
        "createAt": "2022-12-29T02:16:12.969Z",
        "message": "퍼플북을 통해 생성되었습니다. 백그라>운드 처리 여부 : false"
      },
      {
        "createAt": "2022-12-29T02:16:13.159Z",
        "message": "국가코드(82)의 알림톡(ATA) 1 건이 추가되었습니다."
      },
      {
        "createAt": "2022-12-29T02:16:16.813Z",
        "message": "메시지를 발송했습니다.",
        "oldBalance": 43778082.7,
        "newBalance": 43778078.7,
        "oldPoint": 0,
        "newPoint": 0,
        "totalPrice": 8
      }
    ],
    "status": "COMPLETE",
    "dateSent": "2022-12-29T02:16:16.813Z",
    "scheduledDate": null,
    "dateCompleted": "2022-12-29T02:16:21.683Z",
    "isRefunded": false,
    "flagUpdated": false,
    "prepaid": true,
    "strict": false,
    "masterAccountId": null,
    "allowDuplicates": false,
    "_id": "G4V20221229111612XSXKODV6QRNJTJ5",
    "groupId": "G4V20221229111612XSXKODV6QRNJTJ5",
    "accountId": "111111111111",
    "apiVersion": "4",
    "customFields": {},
    "hint": null,
    "price": {
      "82": {
        "sms": 13,
        "lms": 29,
        "mms": 60,
        "ata": 8,
        "cta": 14,
        "cti": 22,
        "nsa": 6,
        "rcs_sms": 11,
        "rcs_lms": 28,
        "rcs_mms": 58,
        "rcs_tpl": 8
      }
    },
    "dateCreated": "2022-12-29T02:16:12.936Z",
    "dateUpdated": "2022-12-29T02:16:21.683Z"
  }
]
팩스 수신 예시 보기
[
  {
    "statusCode": "4000",
    "tcsResult": 0,
    "logMsg": "FAX 전송이 완료되었습니다.",
    "fileId": "ST01FZ230414025210521Z1IazzVahab",
    "url": "https://cool-storage.s3.ap-northeast-2.amazonaws.com/486/ST01FZ230414025210521Z1IazzVabcd",
    "from": "020000001",
    "to": "030309351234",
    "pageCount": 2,
    "dateReceived": "2023-04-14T01:22:25.000Z"
  },
  {
    "statusCode": "4000",
    "tcsResult": 0,
    "logMsg": "FAX 전송이 완료되었습니다.",
    "fileId": "ST01FZ230414025210521Z1IazzVahac",
    "url": "https://cool-storage.s3.ap-northeast-2.amazonaws.com/486/ST01FZ230414025210521Z1IazzVbcde",
    "from": "020000002",
    "to": "030309351234",
    "pageCount": 3,
    "dateReceived": "2023-04-14T01:22:25.000Z"
  }
]

참고 자료​

통신사 코드 (networkCode)​

코드통신사
45005SKT
45008KT
45006LG U+
45099기타
90901카카오
90902네이버
99999알 수 없음

메시지 상태 코드 (statusCode)​

메시지 상태 코드에 대한 자세한 정보는 메시지 상태 코드 문서에서 확인하세요.