n8n에서 복원력 있는 API 인시던트 추출 워크플로 구축하기
API 인시던트 데이터를 추출하고 형식을 검증하며, 재시도 및 검증 실패를 명확히 드러내고 위험한 후속 조치는 사람의 승인을 거치도록 n8n 워크플로를 설계합니다.
요약 · TL;DR
단계별 n8n 워크플로를 활용해 인시던트 데이터를 가져오고, 분석 전에 필수 필드를 검증하며, 불완전한 레코드가 조용히 통과하지 않도록 실패를 명확히 드러내세요. 재시도 횟수는 제한하고, 데이터를 변경하거나 사람들에게 연락할 수 있는 작업에는 사람의 승인을 받으세요.
핵심 요점
- API 추출, 검증, 진단, 조치를 분리해 각 실패를 명확히 파악할 수 있게 하세요.
- 응답 계약을 명시적으로 검증하세요. HTTP 요청이 성공했다고 해서 인시던트 데이터를 사용할 수 있다는 뜻은 아닙니다.
- 일시적인 요청 실패는 횟수를 제한해 재시도하되, 재시도 소진과 유효하지 않은 레코드는 각각 별도의 검토 경로로 보내세요.
- 중요한 도구 호출에는 사람의 승인을 사용하고, 이를 추출 데이터 검증의 대체 수단으로 삼지 마세요.
목차 (8)
워크플로 설계 원칙: 자동으로 진단하고, 신중하게 변경하기
API 인시던트 워크플로에서는 “요청 성공”을 “데이터를 안전하게 사용할 수 있음”과 같은 의미로 취급해서는 안 됩니다. 서비스가 누락된 필드, 비어 있는 인시던트 목록, 또는 배포 후 변경된 응답 구조와 함께 HTTP 200을 반환할 수 있습니다. n8n에서는 추출과 검증을 별도의 단계로 나누고, 각 실패를 이름이 지정된 경로로 분기하세요.
실용적인 흐름은 다음과 같습니다. Schedule 또는 Webhook 트리거 → HTTP Request → 응답 정규화 → 필수 필드 검증 → 진단 요약 생성 → 알림 또는 검토. 레코드 수정, 티켓 생성, 외부 메시지 발송처럼 결과가 중요한 작업은 필요에 따라 사람의 판단을 거치도록 하세요.
아래 예시는 설명을 위한 것입니다. 노드 레이블, 응답 형태, 설정은 n8n 버전과 API에 따라 달라집니다. 테스트를 거친 워크플로 내보내기 파일이 아닙니다.
사전 준비 및 응답 계약
노드를 만들기 전에 인시던트 엔드포인트, 인증 방식, 요청 제한, 진단에 실제로 필요한 필드를 확인하세요. 예를 들어 API가 incidents 배열이 포함된 객체를 반환하고, 각 인시던트에 ID, 상태, 타임스탬프가 있다고 가정해 보겠습니다. 요청이 성공했다는 이유만으로 응답 구조를 추측하지 말고, API 문서나 실제 응답을 통해 확인하세요.
비밀 정보를 Code 노드에 직접 넣지 말고 n8n의 자격 증명 시스템에 저장된 자격 증명을 사용하세요. 유용한 결과가 무엇인지도 정하세요. 인시던트가 없을 때 빈 배열은 유효할 수 있지만, 배열 자체가 누락되었다면 호환되지 않는 응답 변경일 수 있습니다.
추출 및 제한된 재시도 설정
- 정기 점검에는 Schedule Trigger를 추가하고, 상위 시스템이 진단을 시작하는 경우에는 Webhook을 추가합니다.
- 인시던트 엔드포인트, 필수 쿼리 매개변수, 설정된 인증 정보를 사용해 HTTP Request 노드를 추가합니다.
- 시간 제한을 설정하고, 사용 중인 버전에서 지원된다면 노드의 실패 시 재시도 동작도 설정합니다. 재시도 횟수는 적게 설정하고 API의 요청 제한에 맞는 지연 시간을 적용하세요. 재시도 횟수를 무제한으로 설정하지 마세요. 실행 실패가 길어지고 장애 중 부하가 더해질 수 있습니다.
- HTTP 상태 코드와 본문을 확인할 수 있도록 응답 정보를 충분히 보존하세요. 사용 중인 n8n 버전에서 응답 옵션을 확인하세요. 세부 설정은 버전에 따라 달라질 수 있습니다.
- 요청 재시도를 모두 소진한 경우 명시적인 실패 경로로 분기하세요. 워크플로 설계에 따라 노드의 오류 출력이나 전용 오류 워크플로를 사용합니다. 알림에는 실행 ID, 엔드포인트 레이블, 확인할 수 있다면 시도 관련 정보, 오류 메시지를 포함하세요. 인증 헤더나 토큰은 절대로 로그에 남기지 마세요.
시간 초과나 재시도 가능한 서버 응답처럼 일시적인 상황에는 재시도가 적절합니다. 하지만 잘못된 자격 증명, 형식이 잘못된 요청, 스키마 불일치를 해결해 주지는 않습니다. API 문서에 Retry-After가 명시되어 있다면 즉시 재시도하지 말고 해당 값을 따르세요.
진단 전에 검증하기
성공한 응답 다음에 Code 노드를 배치해 다음 단계에서 사용할 필드를 확인하세요. 아래 예시는 앞 노드가 응답 본문을 body로 제공한다고 가정합니다. HTTP Request 설정에 맞춰 속성 경로를 조정하세요.
const body = $json.body;
const valid =
body !== null &&
typeof body === 'object' &&
Array.isArray(body.incidents) &&
body.incidents.every((incident) =>
incident &&
typeof incident.id === 'string' &&
typeof incident.status === 'string' &&
typeof incident.timestamp === 'string'
);
if (!valid) {
return [{
json: {
validationFailed: true,
reason: 'Expected incidents array with id, status, and timestamp',
receivedType: Array.isArray(body) ? 'array' : typeof body,
executionId: $execution.id
}
}];
}
return body.incidents.map((incident) => ({
json: {
validationFailed: false,
incidentId: incident.id,
status: incident.status,
timestamp: incident.timestamp
}
}));
이는 계약을 간단히 확인하는 예시일 뿐, 완전한 JSON Schema 검증기는 아닙니다. 필요한 경우 도메인별 검사를 추가하세요. 예를 들어 타임스탬프 형식을 검증하거나, 상태 값을 API에 문서화된 값으로 제한할 수 있습니다. 누락된 필드를 임의의 기본값으로 조용히 대체하지 마세요. IF 노드를 사용해 validationFailed 항목은 스키마 변경 알림이나 검토 대기열로 보내고, 유효한 레코드는 진단 단계로 전달하세요.
실패를 명확히 드러내기
문제 유형에 따라 신호를 따로 설계하세요.
| 신호 | 의미 | 권장 대응 |
|---|---|---|
| 재시도 후에도 요청 실패 | API 데이터를 가져오지 못함 | 실행 ID와 민감 정보를 제거한 오류 세부 정보로 알림 |
| 검증 실패 | 응답은 왔지만 예상한 계약을 충족하지 않음 | 민감 정보를 제거한 샘플을 보존하고 변경된 응답 구조를 검토 |
| 유효한 응답, 인시던트 없음 | 데이터 추출은 성공했지만 레코드가 없음 | 비어 있는 정상 결과로 기록하고, 정책상 필요하지 않다면 호출 알림을 보내지 않음 |
| 진단 불확실성 | 데이터는 유효하지만 확신할 만한 설명을 뒷받침하지 않음 | 원인을 단정하지 말고 사람의 검토를 요청 |
폴링 주기에 맞춰 알림 임계값을 정하세요. 재시도할 때마다 별도 알림을 보내면 한 번의 장애로 알림이 과도하게 발생할 수 있습니다. 최종 실행 실패 시 알림을 보내거나 실패를 집계하세요.
중요한 작업에는 사람의 검토 추가하기
가능하면 진단은 읽기 전용으로 유지하세요. 인시던트를 추출하고 관련 필드를 요약해 보고서를 보내는 방식입니다. AI Agent가 도구를 호출한다면 입력을 검증된 데이터로 제한하고, 인시던트 수정, 레코드 삭제, 외부 메시지 발송과 같은 작업에는 승인을 요구하세요.
n8n 문서에서는 AI Agent에 연결된 일부 도구에 대한 사람의 검토 기능을 설명합니다. 워크플로는 승인 또는 거절을 기다리며 일시 중지되고, 승인되면 제안된 입력으로 도구가 실행됩니다. 문서에 설명된 승인 채널에는 Slack, Telegram, n8n Chat 등이 포함됩니다. 검토자에게 도구 이름과 매개변수, 인시던트 ID, 작업 제안의 간결한 이유를 보여주세요. 승인이 거절되었을 때 어떻게 해야 할지도 Agent에 지정하세요. 거절을 다른 중요한 도구를 시도해도 된다는 허가로 취급해서는 안 됩니다. n8n의 휴먼 인 더 루프 문서를 참고하세요.
이 문서에 설명된 기능은 AI Agent의 도구 호출에 관한 것입니다. 일반 워크플로에서는 AI Agent 검토 기능이 모든 노드를 자동으로 제어한다고 가정하지 말고, 사용 환경에 적합한 사람 검토 작업이나 승인 단계를 설계하세요.
문제 해결 체크리스트
- 검증기가 모든 응답을 거부함: HTTP Request의 실제 출력 결과를 확인하고, 가정한 본문 경로를 수정하세요. API는 결과를 다른 방식으로 감싸 반환하는 경우가 많습니다.
- 재시도해도 해결되지 않음: 자격 증명, 요청 매개변수, 요청 제한, 오류의 일시성 여부를 확인하세요. 재시도 횟수를 늘리는 대신 영구적인 요청 오류를 수정하세요.
- 인시던트 필드가 누락됐는데도 워크플로가 성공함: 요약 또는 작업 노드보다 먼저 검증이 실행되는지 확인하고, 필드 누락과 잘못된 형식의 값을 모두 테스트하세요.
- 검토자가 제안된 작업을 판단하기 어려움: 출처가 된 인시던트, 제안된 매개변수, 승인 시 결과를 명확하게 포함하세요. 비밀 정보와 불필요한 개인 정보는 제외하세요.
- 새 API 응답 때문에 진단이 실패함: 스키마 실패를 별도의 신호로 보내고, API가 의도한 변경인지 확인한 뒤에만 계약을 업데이트하세요.
결론
견고한 n8n 인시던트 추출 워크플로는 요청 실패, 유효하지 않은 데이터, 진단 가능한 유효 데이터라는 세 가지 결과를 명확히 구분합니다. 일시적인 데이터 가져오기 문제에는 횟수를 제한한 재시도를 사용하고, 분석 전에 계약을 명시적으로 확인하며, 중요한 도구 작업에는 사람의 승인을 받으세요. 이렇게 분리하면 불완전한 응답이 안전하지 않은 결정을 유도하지 않으면서 실패를 더 쉽게 조사할 수 있습니다.
FAQ
HTTP 200 응답이면 인시던트 데이터가 유효한가요?
아니요. 요청이 성공 상태를 반환했다는 뜻일 뿐, 본문이 비어 있거나 형식이 잘못되었거나 필드가 누락되었을 수 있습니다. 진단에 사용하기 전에 응답 계약을 검증하세요.
스키마 검증 실패 시 재시도해야 하나요?
대체로 그렇지 않습니다. 스키마 불일치는 동일한 요청을 다시 보내기보다 조사하거나 계약을 의도적으로 업데이트해야 할 가능성이 높습니다. 별도의 검토 또는 알림 경로로 보내세요.
n8n에서 모든 워크플로 노드 실행 전에 승인을 요구할 수 있나요?
인용한 n8n 문서는 AI Agent에 연결된 일부 도구의 사람 검토 기능을 설명합니다. 이 기능이 표준 워크플로의 임의 노드를 제어한다고 설명하지는 않습니다.
인시던트 실패 알림에는 무엇을 포함해야 하나요?
워크플로 실행 식별자, 민감 정보를 제거한 오류 또는 검증 실패 이유, 조사에 필요한 엔드포인트 맥락을 포함하세요. 자격 증명, 인증 헤더, 불필요한 민감 응답 데이터는 제외하세요.
관련 글
Guides
검증된 출처와 사람 검토를 갖춘 n8n 문서 Q&A 워크플로 구축하기
문서에서 근거를 추출하고, 구조화된 답변을 검증하며, 안전하게 재시도하고, 불확실한 결과는 사람에게 검토를 요청하는 n8n 워크플로를 설계합니다.
Guides
n8n에서 복구 가능한 데이터 추출 워크플로 구축하기
레코드를 검증하고 일시적 실패를 재시도하며, 중복 쓰기 없이 예외를 담당자에게 전달하는 n8n 추출 워크플로를 설계합니다.
Guides
n8n에서 개인정보를 고려한 데이터 추출 워크플로 구축하기
구조화된 출력을 검증하고, 실패를 안전하게 처리하며, 민감한 작업을 사람의 검토로 연결하는 n8n 추출 워크플로를 설계합니다.
Guides
검증, 재시도, 사람의 승인을 포함한 n8n 지원 티켓 분류 워크플로 구축
지원 티켓 필드를 추출하고, 검증하고, 오류를 처리하며, 영향이 큰 작업 전에 사람의 승인을 요구하는 n8n 워크플로를 설계합니다.