[n8n] 학교/학원용 출석 체크 웹훅

moonlang -
1월 6, 2026
Legacy Knowledge (Tilnote)

학교/학원용 “출석 체크 웹훅”은 “출석 페이지 → n8n 웹훅 → 시트/DB 기록 → 보호자 알림”까지 한 번에 처리하는 HTTP 기반 출석 자동화 흐름이다.n8n+1​\
아래 문서는 이 흐름을 구현하기 위한 기술 설계와 n8n 워크플로우 구조, 필드 정의, 예시 요청/응답을 정리한 것이다.n8n-docs.teamlab+1​

1. 전체 아키텍처 개요

  • 클라이언트: 웹/모바일 출석 화면(예: React/Next.js, WebView, 간단한 HTML 폼 등)이 n8n Webhook URL로 JSON POST.

  • 백엔드/오케스트레이션: n8n Webhook 트리거 → 학생 검증(시트/DB 조회) → 출석 기록 저장(Google Sheets 또는 RDB) → KakaoTalk/문자 발송(HTTP Request 노드).n8n+1​

  • 데이터 저장소:

  • 학생 마스터: students 시트 또는 DB 테이블(학생 ID, 이름, 학년, 보호자 연락처 등).n8n+1​

  • 출석 로그: attendance_logs 시트 또는 DB 테이블(날짜, 시간, 학생 ID, 상태, 원본 요청 등).n8n​

2. Webhook API 스펙

2.1 엔드포인트

  • 메서드: POST.n8n​

  • URL: n8n Webhook 노드가 생성하는 Production URL (예: https://n8n.example.com/webhook/attendance-check).n8n+1​

  • Content-Type: application/json.

2.2 요청 바디 (예시 스키마)

json

{ "studentId": "S2025001", "timestamp": "2025-11-30T09:05:23+09:00", "status": "IN", "deviceId": "KIOSK-01", "meta": { "location": "MAIN_CAMPUS_1F", "classCode": "ENG-301" } }

권장 필드 정의:

  • studentId (string, required): 학원/학교 내부에서 사용하는 고유 학생 ID.

  • timestamp (string, ISO-8601, required): 클라이언트 기준 출석 시각(예: 한국 시간).

  • status (string, required): "IN"(입실), "OUT"(퇴실), "LATE"(지각) 등 사전 정의된 코드.

  • deviceId (string, optional): 키오스크/단말기 식별자.

  • meta (object, optional): 교실 코드, 캠퍼스, IP, 브라우저 정보 등 확장용.

2.3 응답

  • 성공:
json

{ "success": true, "message": "ATTENDANCE_RECORDED", "studentName": "홍길동", "normalizedTimestamp": "2025-11-30T09:05:23+09:00", "status": "IN" }

  • 오류(예시):
json

{ "success": false, "errorCode": "STUDENT_NOT_FOUND", "message": "Unknown studentId" }

Webhook 노드의 Response Data를 커스텀으로 설정하면 위와 같이 JSON 응답을 직접 구성할 수 있다.n8n-docs.teamlab+1​

3. n8n 워크플로우 설계

3.1 노드 구성 개요

  1. Webhook (Trigger) – 출석 요청 수신.n8n+1​

  2. Function / Set (입력 정규화) – 필드 이름/형식 정리, 기본값 설정.

  3. 학생 정보 조회 노드

  4. Google Sheets 노드(Get Row(s)) 또는 DB 노드(MySQL/Postgres 등)에서 studentId로 학생 정보를 조회.youtube​n8n​

  5. IF (검증 분기) – 학생 존재 여부, 요청 유효성 검사.

  6. 출석 로그 저장 노드

  7. Google Sheets Append Row 또는 DB INSERT.n8n+1​

  8. KakaoTalk/문자 발송 노드

  9. HTTP Request 노드로 카카오톡 나에게 보내기/알림톡/문자 API 호출.wikidocs+1​

  10. Webhook 응답 노드(Respond to Webhook 또는 Webhook 노드 응답 설정) – 최종 JSON 응답 반환.n8n​

4. 단계별 상세 설정

4.1 Webhook 노드

  • HTTP Method: POST.n8n​

  • Authentication:

  • 초간단 버전: 쿼리 파라미터/헤더의 사설 토큰 검사(예: x-api-key).

  • 고급: IP 화이트리스트, 서명 검증, TLS 강제 등은 리버스 프록시 및 별도 로직으로 보강.n8n​

  • Response Mode:

  • 동기 응답: 출석 기록과 보호자 알림까지 모두 처리 후 한 번에 응답.

  • 또는 “기록만 하고 바로 OK 응답, 알림은 비동기로 처리” 구조도 가능.

4.2 입력 정규화 (Function / Set)

예시 로직:

  • timestamp가 비어 있으면 서버 현재 시간을 사용.

  • status 값이 소문자일 경우 대문자로 변환.

  • meta가 없으면 빈 객체 생성.

이 단계에서 내부 공통 필드 구조를 확정해 두면 이후 노드에서 필드 참조가 단순해진다.n8n-docs.teamlab​

4.3 학생 정보 조회

Google Sheets 예시

  • 노드: Google Sheets.n8n​

  • Operation: Get Row(s) 또는 Read에 해당하는 연산.

  • 필터: studentId 열이 Webhook에서 받은 studentId와 같은 행.

  • 주요 컬럼:

  • studentId

  • name

  • grade

  • parentName

  • parentPhone

  • kakaoUserId 또는 보호자 카카오 식별값.

DB 예시

  • 노드: MySQL/Postgres 노드.

  • 쿼리 예시:\
    SELECT * FROM students WHERE student_id = {{ $json.studentId }} LIMIT 1;

4.4 검증(IF 노드)

검증 조건:

  • 학생 행이 1개 이상인지.

  • status가 허용된 코드 목록(IN, OUT, LATE 등)에 포함되는지.

  • 시간대(예: 새벽 2시 출석 시 경고 플로우) 검증 등.

분기:

  • 학생 없음 → Webhook 응답에 STUDENT_NOT_FOUND 에러 반환, 로그 시트/DB에 에러 기록(선택).

  • 유효 → 출석 로그 저장 단계로 진행.

5. 출석 로그 저장

5.1 Google Sheets에 저장

  • 노드: Google Sheets, Operation: Append Row.youtube​n8n​

  • 대상 시트: attendance_logs.

  • 예시 컬럼:

컬럼명 설명
date YYYY-MM-DD 형식 날짜
time HH:mm:ss 또는 ISO 타임 부분
timestamp 전체 ISO 타임스탬프
studentId 학생 ID
studentName 학생 이름
status IN / OUT / LATE 등
deviceId 단말기 ID
classCode 수업 코드
location 캠퍼스/교실 정보
createdAt 서버 기록 시간
  • 값 매핑은 Webhook + 학생 정보 조회 결과를 조합해서 Expression으로 작성.

5.2 DB에 저장 (선택)

  • MySQL/Postgres 노드, INSERT 쿼리 사용.

  • 출석 통계를 복잡하게 낼 계획이면 DB를 기본 저장소로 두고 Sheets는 리포트/대시보드 용도로만 사용하는 것도 좋다.n8n​

6. KakaoTalk/문자 발송

6.1 KakaoTalk “나에게 보내기” 또는 보호자에게 보내기

  • 인증/토큰 발급 절차:

  • 카카오 개발자 콘솔에서 앱 생성 → REST API 키 확보 → OAuth2로 액세스 토큰 발급 → talk_message 스코프 동의.wikidocs​

  • n8n 설정:

  • 노드: HTTP Request.youtube​wikidocs​

  • Method: POST.

  • URL: 예) https://kapi.kakao.com/v2/api/talk/memo/default/send (나에게 보내기 기준).wikidocs​

  • Headers:

    • Authorization: Bearer {{ $json.accessToken }}

    • Content-Type: application/x-www-form-urlencoded

  • Body:

    • template_object에 JSON 문자열(텍스트, 링크 등)을 구성.wikidocs​

메시지 텍스트 예시(구성 아이디어):

  • [출석 알림] 홍길동 학생이 11:05에 ENG-301 수업에 입실했습니다.

  • [퇴실 알림] 홍길동 학생이 12:40에 학원을 퇴실했습니다.

보호자에게 직접 보내려면 카카오톡 비즈 메시지(알림톡/친구톡) 또는 문자 발송 업체(SMS 게이트웨이)의 HTTP API를 사용하고, 동일하게 HTTP Request 노드로 연동한다.inflearn+1​

6.2 발송 실패 처리

  • IF 노드로 HTTP Request의 응답 코드/바디를 검사.

  • 실패 시:

  • 재시도 큐(예: 별도 시트/DB 테이블)에 적재.

  • 관리자에게 슬랙/이메일로 “해당 보호자 알림 실패” 통지.

7. 보안·운영 고려 사항

  • Webhook 보호:

  • IP 화이트리스트(출석 키오스크/내부 서버 IP만 허용) 또는 API Key 검사.n8n+1​

  • HTTPS 강제, 프록시 레벨에서 TLS 종료 설정.n8n​

  • 로그 및 모니터링:

  • n8n 실행 로그 + 출석 로그 시트/DB로 이중 기록.

  • 예외 발생 시 슬랙/이메일 알림 워크플로우 추가.

  • 재사용성:

  • 같은 구조를 “입실/퇴실 전용 웹훅”, “온라인 수업 출석 웹훅” 등으로 분기해서 재사용 가능.n8n-docs.teamlab​

8. 간단 시퀀스 흐름

  1. 학생이 출석 페이지에서 QR 스캔 → 출석 버튼 클릭.

  2. 프론트엔드가 POST /attendance-check-webhook에 JSON 전송.

  3. Webhook 노드가 요청 수신 → 입력 정규화.

  4. 학생 마스터 시트/DB 조회 → 검증.

  5. 유효하면 출석 로그 시트/DB에 Append.

  6. KakaoTalk/문자 API 호출로 보호자에게 알림 전송.

  7. Webhook 응답으로 { success: true, ... } 반환, 클라이언트에 “출석 완료” 표시.n8n+2​

  8. https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/

  9. https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.googlesheets/

  10. https://n8n-docs.teamlab.info/integrations/builtin/core-nodes/n8n-nodes-base.webhook/workflow-development/

  11. https://wikidocs.net/290905

  12. https://n8n.io/integrations/google-docs/and/google-sheets/

  13. https://docs.n8n.io/hosting/configuration/configuration-examples/webhook-url/

  14. https://www.youtube.com/watch?v=M3z_X_hiUC8

  15. https://www.inflearn.com/community/questions/1626403/n8n%EA%B3%BC-%EC%B9%B4%EC%B9%B4%EC%98%A4%ED%86%A1-%EC%97%B0%EA%B3%84-%EA%B0%95%EC%9D%98%EB%8F%84-%EB%B6%80%ED%83%81%EB%93%9C%EB%A6%BD%EB%8B%88%EB%8B%A4

  16. https://www.youtube.com/watch?v=PpvlLfufV_0

  17. https://www.youtube.com/watch?v=omzkPzQHS8k

  18. https://docs.gotohuman.com/Integrations/n8n-http

  19. https://n8n.io/integrations/google-sheets/

  20. https://developer.unipile.com/docs/create-webhook-n8n

  21. https://docs.n8n.io/integrations/builtin/app-nodes/n8n-nodes-base.googledocs/

  22. https://pipedream.com/apps/n8n-io/integrations/kakao

  23. https://www.youtube.com/watch?v=pWGXlZBGu4k

  24. https://www.youtube.com/watch?v=Gi1yHX7VhMQ

  25. https://docs.n8n.io/integrations/builtin/trigger-nodes/n8n-nodes-base.googlesheetstrigger/

  26. https://vol2.tistory.com/entry/n8n-s6-%EB%B9%84%EC%A6%88%EB%8B%88%EC%8A%A4-%EC%98%81%EC%96%B4%EB%B4%87-%EC%B9%B4%EC%B9%B4%EC%98%A4%ED%86%A1-%EB%A9%94%EC%8B%9C%EC%A7%80-%EC%9E%90%EB%8F%99%ED%99%94-%ED%95%98%EA%B8%B0-%EB%82%98%EC%97%90%EA%B2%8C-%EB%B3%B4%EB%82%B4%EA%B8%B0

  27. https://www.gpters.org/nocode/post/create-chatbot-n8n-create-efWD8L8dCetwryc

#No Tag

No responses yet

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다