웹훅

웹훅을 사용하여 SMS 메시지 수신 또는 팩스 수신과 같은 이벤트가 발생하면 사용자가 설정한 URL로 HTTP요청(POST)를 보냅니다.
'그룹 리포트'를 제외한 요청에는 수신 전화 번호나 상태 등 세부 정보가 포함됩니다.
요청 후 HTTP Status Code를 2xx으로 리턴해야 전달 성공으로 판단합니다.

종류

제공 되는 웹훅의 종류와 설명은 아래와 같습니다.

메시지 리포트 : 메시지 처리가 완료되었을 때 호출됩니다.
그룹 리포트 : 그룹 내 모든 메시지 처리가 완료되었을 때 호출됩니다.
팩스 수신 : 팩스가 수신되었을 때 호출됩니다.

데이터 사이즈

500,000byte(500kB)까지 데이터가 한 요청에 포함되어 전송 될 수 있습니다.
한글은 3byte, 영문/숫자의 경우 1byte의 크기로 계산됩니다.
사이즈 조정을 원하실 경우 고객센터에 문의 부탁드립니다.

타임아웃

5초의 타임아웃 시간을 갖고 있으며,
해당 시간이 경과되면 실패로 처리됩니다.
타임아웃 시간 조정을 원하실 경우 고객센터에 문의 부탁드립니다.

발송 간격

각 요청마다 1초의 대기 시간을 갖고 있으며,
대기 시간 조정을 원하실 경우 고객센터에 문의 부탁드립니다.
예) 첫번째 요청 -> 1초 대기 -> 두번째 요청

실패 후 재시도

웹훅 데이터를 보냈을 떄 HTTP Status Code 2xx가 리턴되지 않았거나 전달에 실패하였다면 아래와 같은 순서로 재시도 합니다.
첫 시도를 포함 총 8번의 데이터 전달 시도를 하고, 모두 실패 시 웹훅은 비활성화 됩니다.
재시도 대기시간은 이전 대기시간의 두배씩 증가됩니다.
비활성화 시 재활성화가 될 때 까지 데이터 전달 시도를 하지 않습니다.

첫번째 시도 실패 : 15분뒤
두번째 시도 실패: 30분뒤
세번째 시도 실패: 1시간뒤
네번째 시도 실패: 2시간뒤
다섯번째 시도 실퍠: 4시간뒤
여섯번째 시도 실퍠: 8시간뒤
일곱번째 시도 실퍠: 16시간뒤
여덞번째 시도 시패(마지막): 비활성화

데이터 예시

사용자가 설정한 URL에 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 값 의미

코드	네트워크
45005	SKT
45008	KT올레
45006	LG유플러스
45099	ETC
90901	카카오
90902	네이버
99999	Unknown carrier

statusCode 값 의미

메시지 상태 코드 에서 확인하세요.

웹훅

종류​

데이터 사이즈​

타임아웃​

발송 간격​

실패 후 재시도​

데이터 예시​

참고 자료​

networkCode 값 의미​

statusCode 값 의미​

종류