리스토베이 폼 제출 시, 다른 앱이나 URL로 정보를 보낼 수 있습니다.

1. 작동 원리

2. 연동 방법

3. 요청 실패 및 재시도

4. 웹훅 관리

5. 웹훅 이벤트 예시

작동 원리

연동 방법

1️⃣

• 결과/연동 메뉴 아래의 외부 앱 연동을 클릭해주세요.

 

2️⃣

• 웹훅 연결하기 클릭

• 설문 당 최대 3개 까지 등록 가능

 

3️⃣

Endpoint URL

• JSON 페이로드로 POST 요청을 처리합니다.

• 3초 이내에 성공 상태 코드(2XX)를 반환합니다.

Signing secret

• 이 옵션이 활성화되면 웹훅 요청에 Listovey-Signature헤더가 포함됩니다.

• 이 헤더의 값은 웹훅 페이로드의 SHA256 암호화 해시입니다.

const crypto = require('crypto')

app.use(express.json());

app.post('/webhook', (req, res) => {
  const payload = req.body;
  const listoveySignature = req.headers['listovey-signature'];

  // 'SIGNING_SECRET' 부분을 리스토베이에서 등록한 Signing secret 값으로 변경
  const mySigningSecret = 'SIGNING_SECRET';

  // signing secret과 payload를 사용하여 계산
  const payloadSignature = crypto.createHmac('sha256', mySigningSecret)
    .update(JSON.stringify(payload))
    .digest('base64');

  // listoveySignature 와 payloadSignature 값을 비교
  if (signature === payloadSignature) {
    // 유효한 서명
    res.status(200).send('success.');
  } else {
    // 유효하지 않은 서명
    res.status(401).send('invalid signature.');
  }
});

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

import static spark.Spark.*;

public class Main {

    public static void main(String[] args) {
        post("/webhook", (req, res) -> {
            String payload = req.body();
            String listoveySignature = req.headers("listovey-signature");

            // 'SIGNING_SECRET' 부분을 리스토베이에서 등록한 Signing secret 값으로 변경
            String mySigningSecret = "SIGNING_SECRET";

            // signing secret과 payload를 사용하여 계산
            String payloadSignature = calculateHmacSHA256(payload, mySigningSecret);

            // listoveySignature 와 payloadSignature 값을 비교
            if (listoveySignature.equals(payloadSignature)) {
                // 유효한 서명
                return "success.";
            } else {
                // 유효하지 않은 서명
                return "invalid signature.";
            }
        });
    }

    private static String calculateHmacSHA256(String data, String key) throws NoSuchAlgorithmException, InvalidKeyException {
        Mac sha256Hmac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(key.getBytes(), "HmacSHA256");
        sha256Hmac.init(secretKey);
        byte[] hmacData = sha256Hmac.doFinal(data.getBytes());
        return Base64.getEncoder().encodeToString(hmacData);
    }
}

import hashlib
import hmac
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    payload = request.json
    listovey_signature = request.headers.get('listovey-signature')

    # 'SIGNING_SECRET' 부분을 리스토베이에서 등록한 Signing secret 값으로 변경
    my_signing_secret = 'SIGNING_SECRET'

    # signing secret과 payload를 사용하여 계산
    payload_signature = hmac.new(my_signing_secret.encode('utf-8'), 
                                  msg=json.dumps(payload).encode('utf-8'), 
                                  digestmod=hashlib.sha256).digest()

    payload_signature = payload_signature.hex()

    # listovey_signature 와 payload_signature 값을 비교
    if listovey_signature == payload_signature:
        # 유효한 서명
        return 'success.', 200
    else:
        # 유효하지 않은 서명
        return 'invalid signature.', 401

if __name__ == '__main__':
app.run()

요청 실패 및 재시도

• HTTP 상태가 410 Gone 404 Not Found 로 수신되면 재시도가 수행되지 않고 웹후크가 즉시 비활성화되며 가입된 이메일 계정으로 안내 드립니다.

• 다른 HTTP 코드가 수신되면 5분, 30분, 1시간, 2시간, 6시간 후에 엔드포인트에 대한 요청을 5번 다시 시도합니다.

• HTTP 상태가  429 Too Many Requests 408 Timeout 503 Service Unavailable 423 Locked 으로 수신되면 재시도 시간에 1~3,000초 사이로 시간이 추가되어 다시 시도합니다.

자동 비활성화

웹훅 관리

• 이 로그에는 웹훅 엔드포인트에 대한 최근 31일 동안의 요청을 확인 할 수 있습니다.

• 재발송 기능으로 실패한 이벤트에 대해 수동으로 다시 발송할 수 있습니다.

• 테스트 이벤트 발송으로 임의의 데이터를 받아 볼 수 있습니다. (플랜과 상관 없이 이용 가능)

웹훅 이벤트 예시

POST /[webhook_url] HTTP/1.1
"content-type": "application/json; charset=UTF-8"
"user-agent": "Listovey webhook"

{
    "eventId": "912ba841-32a8-4e64-b7f9-c92f480b0dfc",
    "eventType": "FORM_RESPONSE",
    "createdAt": "2024-03-05T03:26:37.430Z",
    "data": {
      "response": {
        "responseId": "R17E1Gc",
        "createdAt": "2024-03-05T03:26:37.402Z",
        "submittedAt": "2024-03-05T03:26:37.402Z"
      },
      "form": {
        "formId": "S7877",
        "title": "전체문항",
        "fields": [
          {
            "id": "Q114003",
            "no": 1,
            "title": "단일선택형",
            "type": "SINGLE-CHOICE",
            "choices": [
              {
                "id": "_01163458",
                "text": "선택 1"
              },
              {
                "id": "_01163459",
                "text": "선택 2"
              }
            ],
            "value": {
              "id": "_01163458",
              "commentValue": "TEST"
            }
          },
          {
            "id": "Q114004",
            "no": 2,
            "title": "다중선택형",
            "type": "MULTI-CHOICE",
            "choices": [
              {
                "id": "_0242743",
                "text": "선택 1"
              },
              {
                "id": "_0242744",
                "text": "선택 2"
              }
            ],
            "value": [
              {
                "id": "_0242743",
                "commentValue": "TEST"
              }
            ]
          },
          {
            "id": "Q114005",
            "no": 3,
            "title": "드롭다운형",
            "type": "DROPDOWN",
            "choices": [
              {
                "id": "_214436",
                "text": "옵션 1"
              },
              {
                "id": "_214437",
                "text": "옵션 2"
              }
            ],
            "value": [
              "_214436"
            ],
            "commentValue": ""
          },
          {
            "id": "Q114006",
            "no": 4,
            "title": "단일선택형 매트릭스",
            "type": "SINGLE-MATRIX",
            "rows": [
              {
                "id": "row_0318066",
                "text": "항목 1"
              },
              {
                "id": "row_0318067",
                "text": "항목 2"
              }
            ],
            "columns": [
              {
                "id": "col_0316013",
                "text": "선택 1"
              },
              {
                "id": "col_0316014",
                "text": "선택 2"
              }
            ],
            "value": {
              "row_0318066": "col_0316013",
              "row_0318067": "col_0316013"
            },
            "commentValue": ""
          },
          {
            "id": "Q114007",
            "no": 5,
            "title": "다중선택형 매트릭스",
            "type": "MULTI-MATRIX",
            "rows": [
              {
                "id": "row_044827",
                "text": "항목 1"
              },
              {
                "id": "row_044828",
                "text": "항목 2"
              }
            ],
            "columns": [
              {
                "id": "col_044000",
                "text": "선택 1"
              },
              {
                "id": "col_044001",
                "text": "선택 2"
              }
            ],
            "value": {
              "row_044827": [
                "col_044000"
              ],
              "row_044828": [
                "col_044000"
              ]
            },
            "commentValue": "TEST"
          },
          {
            "id": "Q114008",
            "no": 6,
            "title": "이미지 단일선택형",
            "type": "SINGLE-IMAGE-CHOICE",
            "choices": [
              {
                "id": "_1217029",
                "text": "선택 1"
              },
              {
                "id": "_1217030",
                "text": "선택 2"
              }
            ],
            "value": {
              "id": "_1217029",
              "commentValue": "TEST"
            }
          },
          {
            "id": "Q114009",
            "no": 7,
            "title": "이미지 다중선택형",
            "type": "MULTI-IMAGE-CHOICE",
            "choices": [
              {
                "id": "_1311411",
                "text": "선택 1"
              },
              {
                "id": "_1311412",
                "text": "선택 2"
              }
            ],
            "value": [
              {
                "id": "_1311411",
                "commentValue": ""
              }
            ]
          },
          {
            "id": "Q114010",
            "no": 8,
            "title": "가로형 평가척도",
            "type": "HORIZONTAL-SCALE",
            "choices": [
              {
                "id": "_0558500",
                "no": 1
              },
              {
                "id": "_0558501",
                "no": 2
              },
              {
                "id": "_0558502",
                "no": 3
              },
              {
                "id": "_0558503",
                "no": 4
              },
              {
                "id": "_0558504",
                "no": 5
              }
            ],
            "value": "_0558500",
            "commentValue": ""
          },
          {
            "id": "Q114011",
            "no": 9,
            "title": "가로형 평가척도 그룹",
            "type": "HORIZONTAL-SCACLE-GROUP",
            "rows": [
              {
                "id": "row_0610318",
                "text": "항목 1"
              },
              {
                "id": "row_0610319",
                "text": "항목 2"
              }
            ],
            "columns": [
              {
                "id": "col_0612615",
                "no": 1
              },
              {
                "id": "col_0612616",
                "no": 2
              },
              {
                "id": "col_0612617",
                "no": 3
              },
              {
                "id": "col_0612618",
                "no": 4
              },
              {
                "id": "col_0612619",
                "no": 5
              }
            ],
            "value": {
              "row_0610318": "col_0612615",
              "row_0610319": "col_0612615"
            },
            "commentValue": ""
          },
          {
            "id": "Q114012",
            "no": 10,
            "title": "세로형 평가척도",
            "type": "VERTICAL-SCALE",
            "choices": [
              {
                "id": "_0714754",
                "text": "선택 1",
                "no": 1
              },
              {
                "id": "_0714755",
                "text": "선택 2",
                "no": 2
              },
              {
                "id": "_0714756",
                "text": "선택 3",
                "no": 3
              },
              {
                "id": "_0714757",
                "text": "선택 4",
                "no": 4
              },
              {
                "id": "_0714758",
                "text": "선택 5",
                "no": 5
              }
            ],
            "value": "_0714754",
            "commentValue": ""
          },
          {
            "id": "Q114013",
            "no": 11,
            "title": "세로형 평가척도 그룹",
            "type": "VERTICAL-SCALE-GROUP",
            "rows": [
              {
                "id": "row_081432",
                "text": "항목 1"
              },
              {
                "id": "row_081433",
                "text": "항목 2"
              }
            ],
            "columns": [
              {
                "id": "col_082006",
                "text": "선택 1",
                "no": 1
              },
              {
                "id": "col_082007",
                "text": "선택 2",
                "no": 2
              },
              {
                "id": "col_082008",
                "text": "선택 3",
                "no": 3
              },
              {
                "id": "col_082009",
                "text": "선택 4",
                "no": 4
              },
              {
                "id": "col_082010",
                "text": "선택 5",
                "no": 5
              }
            ],
            "value": {
              "row_081432": "col_082006",
              "row_081433": "col_082006"
            },
            "commentValue": ""
          },
          {
            "id": "Q114014",
            "no": 12,
            "title": "추천형",
            "type": "RECOMMEND",
            "choices": [
              {
                "id": "_146001",
                "text": "선택 1",
                "no": 1
              },
              {
                "id": "_146002",
                "text": "선택 2",
                "no": 2
              },
              {
                "id": "_146003",
                "text": "선택 3",
                "no": 3
              },
              {
                "id": "_146004",
                "text": "선택 4",
                "no": 4
              },
              {
                "id": "_146005",
                "text": "선택 5",
                "no": 5
              }
            ],
            "value": "_146001",
            "commentValue": ""
          },
          {
            "id": "Q114015",
            "no": 13,
            "title": "추천형 그룹",
            "type": "RECOMMEND-GROUP",
            "rows": [
              {
                "id": "row_152142",
                "text": "항목 1"
              },
              {
                "id": "row_152143",
                "text": "항목 2"
              }
            ],
            "columns": [
              {
                "id": "col_153104",
                "text": "선택 1",
                "no": 1
              },
              {
                "id": "col_153105",
                "text": "선택 2",
                "no": 2
              },
              {
                "id": "col_153106",
                "text": "선택 3",
                "no": 3
              },
              {
                "id": "col_153107",
                "text": "선택 4",
                "no": 4
              },
              {
                "id": "col_153108",
                "text": "선택 5",
                "no": 5
              }
            ],
            "value": {
              "row_152142": "col_153104",
              "row_152143": "col_153104"
            },
            "commentValue": ""
          },
          {
            "id": "Q114016",
            "no": 14,
            "title": "타입검사 입력형 - 텍스트",
            "type": "INPUT",
            "kind": "TEXT",
            "value": "TEST"
          },
          {
            "id": "Q114048",
            "no": 15,
            "title": "타입검사 입력형 - 숫자",
            "type": "INPUT",
            "kind": "NUMBER",
            "value": "1"
          },
          {
            "id": "Q114049",
            "no": 16,
            "title": "타입검사 입력형 - 이메일",
            "type": "INPUT",
            "kind": "EMAIL",
            "value": "test@listovey.com"
          },
          {
            "id": "Q114050",
            "no": 17,
            "title": "타입검사 입력형 - 전화번호",
            "type": "INPUT",
            "kind": "PHONE",
            "value": "+82 0100000000"
          },
          {
            "id": "Q114051",
            "no": 18,
            "title": "타입검사 입력형 - 날짜",
            "type": "INPUT",
            "kind": "DATE",
            "value": "2024-03-05"
          },
          {
            "id": "Q114042",
            "no": 19,
            "title": "장문 서술형",
            "type": "TEXTAREA",
            "value": "TEST 1\nTEST 2\nEST 3"
          },
          {
            "id": "Q114043",
            "no": 20,
            "title": "주소 입력형",
            "type": "ADDRESS",
            "value": {
              "zipcode": "01014",
              "address1": "서울 강북구 4.19로11길 6",
              "address2": "1130호"
            }
          },
          {
            "id": "Q114044",
            "no": 21,
            "title": "D&D 순위형",
            "type": "RANKING-DRAG",
            "choices": [
              {
                "id": "_113789",
                "text": "선택 1"
              },
              {
                "id": "_113790",
                "text": "선택 2"
              },
              {
                "id": "_113791",
                "text": "선택 3"
              }
            ],
            "value": [
              "_113789",
              "_113790",
              "_113791"
            ],
            "commentValue": ""
          },
          {
            "id": "Q114045",
            "no": 22,
            "title": "Click 순위형",
            "type": "RANKING-CLICK",
            "choices": [
              {
                "id": "_177231",
                "text": "선택 1"
              },
              {
                "id": "_177232",
                "text": "선택 2"
              },
              {
                "id": "_177233",
                "text": "선택 3"
              }
            ],
            "value": [
              {
                "id": "_177231",
                "commentValue": ""
              },
              {
                "id": "_177232",
                "commentValue": ""
              }
            ]
          },
          {
            "id": "Q114046",
            "no": 23,
            "title": "이미지 Click 순위형",
            "type": "RANKING-IMAGE-CLICK",
            "choices": [
              {
                "id": "_181230",
                "text": "선택 1"
              },
              {
                "id": "_181231",
                "text": "선택 2"
              },
              {
                "id": "_181232",
                "text": "선택 3"
              }
            ],
            "value": [
              {
                "id": "_181230",
                "commentValue": ""
              },
              {
                "id": "_181231",
                "commentValue": ""
              }
            ]
          },
          {
            "id": "Q114047",
            "no": 24,
            "title": "파일 업로드형",
            "type": "FILEUPLOAD",
            "value": {
              "filename": "best.png",
              "filetype": "image/png",
              "filesize": 46828,
              "src": "https://cdn.listovey.com/2205/4775/59855/5b358f18-2bfc-4925-9b06-a31aa64836fb2205477559855.png"
            },
            "commentValue": ""
          },
          {
            "type": "ENDING",
            "choices": [
              {
                "id": "_E10142",
                "text": "완료글 1"
              },
              {
                "id": "_E10143",
                "text": "완료글 2"
              }
            ],
            "value": "_E10142"
          },
          {
            "type": "POINT",
            "value": 11
          }
        ]
      }
    }
  }

Event information

Response information

Form information

Fields information

Value information