알아두면 좋은 점 - Webhook 제한 사항 및 시스템 동작

finlight가 webhook 오류, 재시도, 제한을 어떻게 처리하는지 이해하면 더 안정적인 통합을 구축하고 할당량을 효과적으로 관리할 수 있습니다.

오류 처리 및 재시도

재시도 로직

webhook 전송이 실패하면 finlight는 요청을 자동으로 재시도합니다:

재시도 일정:

• 1차 재시도: 최초 실패 직후
• 2차 재시도
• 3차 재시도

최대 시도 횟수:

• webhook 이벤트당 총 3회 전송 시도
• 각 재시도는 동일한 페이로드와 헤더를 사용합니다
• 모든 재시도는 호출 기록에 기록됩니다

재시도를 유발하는 것

다음의 경우 재시도가 발생합니다:

• HTTP 오류 코드 4xx 및 5xx 응답
• 네트워크 타임아웃(5초 제한)
• 연결 실패(DNS 오류, 거부된 연결)
• SSL/TLS 오류(인증서 문제)

재시도를 유발하지 않는 것

다음의 경우 재시도하지 않습니다:

• HTTP 2xx 응답(성공으로 간주)
• 잘못된 webhook 구성(잘못된 URL)
• 비활성화된 webhook

자동 비활성화 보호

연속 실패 추적

finlight는 할당량을 보호하고 끝없는 실패 시도를 방지하기 위해 연속된 webhook 실패를 추적합니다.

작동 방식:

1. 성공 시 카운터 재설정 - 전송이 성공할 때마다(HTTP 2xx) 실패 카운터가 0으로 재설정됩니다
2. 실패 시 카운터 증가 - 전송이 실패할 때마다 연속 실패 횟수가 증가합니다
3. 10회에서 자동 비활성화 - 10회 연속 실패하면 webhook이 자동으로 비활성화됩니다

자동 비활성화 동작

자동 비활성화가 트리거되는 경우:

• 모든 재시도를 통틀어 10회 연속 전송 실패
• webhook 상태가 "활성화됨"에서 "비활성화됨"으로 변경됩니다
• 자동 비활성화를 알리는 대시보드 알림이 표시됩니다
• 수동으로 다시 활성화할 때까지 추가 webhook 시도 없음

중요 참고 사항:

• 자동 비활성화에 집계되는 것은 연속 실패뿐입니다
• 전송이 한 번이라도 성공하면 카운터가 0으로 재설정됩니다
• 수동 재활성화 필요 - webhook은 자동으로 활성화되지 않습니다
• 모든 실패 유형이 집계됩니다(타임아웃, 4xx, 5xx 응답)

예시 시나리오

시나리오 1: 카운터 재설정

Attempt 1: Failed (counter = 1)
Attempt 2: Failed (counter = 2)
Attempt 3: Success (counter = 0) ← Reset!
Attempt 4: Failed (counter = 1)

시나리오 2: 자동 비활성화

Attempts 1-10: All failed (counter = 10)
→ Webhook automatically disabled

복구 및 재활성화

수동 재활성화 과정

재활성화 단계:

1. 호출 기록을 사용하여 근본 원인을 파악합니다
2. 엔드포인트 문제를 수정합니다(인증, URL, 서버 오류)
3. 상태 설정을 편집하여 webhook 세부 정보에서 webhook을 다시 활성화합니다
4. 대시보드 테스트 버튼으로 webhook을 수동으로 테스트합니다
5. 초기 전송을 모니터링하여 해결을 확인합니다

예방 전략

자동 비활성화 방지:

• 엔드포인트에 적절한 오류 처리를 구현합니다
• 적절한 HTTP 상태 코드를 반환합니다
• webhook 상태를 사전에 모니터링합니다
• webhook 실패에 대한 알림을 설정합니다
• 프로덕션 전에 개발 환경에서 변경 사항을 테스트합니다

할당량 관리

대시보드의 그래프에서 사용량을 확인할 수 있습니다. 사용량은 지연되어 기록된다는 점에 유의하세요.

실패한 요청도 할당량에 집계됨

중요: 실패한 전송을 포함하여 모든 webhook 전송 시도가 구독 할당량에 집계됩니다.

무엇이 집계되는가:

• 최초 전송 시도 - 할당량에 집계됩니다
• 모든 재시도 - 각 재시도가 개별적으로 집계됩니다
• 실패한 전송 - 여전히 할당량을 소비합니다
• webhook 테스트 요청 - 이 또한 할당량에 집계됩니다

할당량 영향 예시:

1 webhook event with 5 failed retry attempts = 5 quota usage
1 webhook event with 1 successful delivery = 1 quota usage

할당량을 효율적으로 관리하기

모범 사례:

• 실패한 재시도를 최소화하기 위해 엔드포인트 문제를 신속히 수정합니다
• 실패 패턴이 있는지 호출 기록을 모니터링합니다
• 프로덕션에서 webhook을 활성화하기 전에 철저히 테스트합니다
• 적절한 상태 코드를 반환하도록 적절한 오류 처리를 사용합니다

할당량 보호: 자동 비활성화 기능은 지속적으로 실패하는 엔드포인트로의 전송을 중단하여 할당량 낭비를 방지하는 데 도움이 됩니다.

webhook 설정 안내는 webhook 기본 문서를 참조하세요. 테스트 및 디버깅은 테스트 가이드를 확인하세요.