# 자동 웹훅 재시도

Hyperclass 마켓플레이스 앱용 자동 웹훅 재시도는 일시적인 속도 제한에 걸려도 중요한 이벤트가 확실히 서버에 도달하도록 보장합니다. HTTP 429 응답에만 재시도하고 랜덤 지연(jitter)을 추가하여 안정성을 높였습니다. 이 가이드는 마켓플레이스 개발자들이 새로운 시스템의 작동 방식을 이해하고 완벽한 전송을 위한 엔드포인트 준비 방법을 안내합니다.

[웹훅 연동 가이드(Webhook Integration Guide)](https://marketplace.gohighlevel.com/docs/webhook/WebhookIntegrationGuide/index.html)도 함께 참고하세요.

***

**목차**

* [마켓플레이스 자동 웹훅 재시도란?](#마켓플레이스-자동-웹훅-재시도란)
* [마켓플레이스 자동 웹훅 재시도의 주요 장점](#마켓플레이스-자동-웹훅-재시도의-주요-장점)
* [재시도 일정](#재시도-일정)
* [재시도 조건](#재시도-조건)
* [지터 보호](#지터-보호)
* [개발자 사용 방법](#개발자-사용-방법)
* [권장 HTTP 응답 코드](#권장-http-응답-코드)
* [자주 묻는 질문](#자주-묻는-질문)

***

## **마켓플레이스 자동 웹훅 재시도란?**

Hyperclass 마켓플레이스에 지능적인 아웃바운드 웹훅 재시도 메커니즘이 내장되었습니다. 앱의 엔드포인트가 HTTP 429 (Too Many Requests)로 응답하면, Hyperclass가 동일한 페이로드를 최대 6번까지 간격을 두고 랜덤 지터와 함께 자동으로 재전송합니다. 다른 모든 상태 코드(2xx 성공, 4xx/5xx 오류)는 최종으로 처리되어 예측 가능한 전송 동작을 제공하고 서버 과부하를 방지합니다.

* **HTTP 429에만 재시도**: 엔드포인트가 429(속도 제한) 응답을 반환할 때만 웹훅 전송을 재시도합니다.
* **지터 보호**: 랜덤한 재시도 타이밍으로 "천둥 같은 무리(thundering herd)" 문제를 방지하고 서버 전체에 부하를 고르게 분산시킵니다.

![자동 웹훅 재시도 다이어그램](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155059526523/original/D2rEyUeb2mzM7rJM8gksL_2qN-t-bce3XA.png?1764451665)

***

## **마켓플레이스 자동 웹훅 재시도의 주요 장점**

* **안정성** – 일시적인 속도 제한 급증으로 인한 이벤트 손실이 더 이상 발생하지 않습니다.
* **예측 가능성** – 고정된 10분 간격(지터 포함)과 6회 시도 제한으로 최악의 지연 시간(약 1시간 10분)을 모델링할 수 있습니다.
* **서버 보호** – 지터가 동시 재시도의 "천둥 같은 무리"를 방지하여 인프라 전체에 부하를 고르게 분산시킵니다.
* **개발자 제어** – 429 외의 다른 상태를 반환하면 추가 재시도를 즉시 중단할 수 있습니다.

***

## **재시도 일정**

모든 재시도는 이전 시도 후 10분 후에 발생하지만, 각 간격은 작은 의사 랜덤 오프셋(지터)으로 랜덤화되어 동기화된 트래픽 급증을 방지합니다. 시스템은 6번의 재시도 후 또는 429가 아닌 응답을 받으면 먼저 오는 쪽에서 중지됩니다. 총 가능한 재시도 기간: 약 1시간 10분.

* **간격**: 재시도 간 10분(지터 포함)
* **최대 시도**: 6회 재시도
* **총 재시도 기간**: 약 1시간 10분

***

## **재시도 조건**

재시도 로직은 개발자가 항상 예상할 수 있도록 의도적으로 좁게 설계되었습니다.

* **재시도 상태 코드**: 429만
* **중지 조건**: 기타 모든 상태(200, 202, 204, 4xx, 5xx 등)
* **5xx 재시도 없음**: 서버 측 실패는 다운된 엔드포인트를 과부하시키지 않도록 영구 실패로 처리됩니다.
* 5xx 서버 오류에는 재시도하지 않으며, 영구 실패로 처리됩니다.

***

## **지터 보호**

각 10분 간격에 랜덤 지터(± N초)가 적용됩니다. 이 작은 변화는 여러 이벤트가 동시에 제한당했을 때 재시도가 모두 같은 순간에 실행되지 않도록 보장하여 전체 서버에서 연쇄적인 속도 제한 적중 위험을 대폭 줄입니다.

***

## **개발자 사용 방법**

이 시스템을 최대한 활용하는 방법입니다:

✅ 성공적인 전송에는 200 OK를 반환하세요.

✅ 내부적으로 처리가 실패해도 수신 확인을 위해 200 OK를 반환하세요:

❌ 절대 필요한 경우에만 오류 코드를 사용하세요:

* 408 → 서버가 너무 느림
* 429 → 요청이 너무 많음
* 5xx → 서버가 다운/손상됨 (재시도 시도 안 함)

***

## **권장 HTTP 응답 코드**

요청을 언제 승인하거나 제한할지 이해하는 것이 중요합니다:

* **200 OK** – 성공적인 처리에는 항상 전송하세요. 다운스트림 작업 큐가 작업을 비동기로 처리하더라도 Hyperclass가 이벤트를 받았다는 것을 알 수 있도록 200을 반환하세요.
* **429 Too Many Requests** – Hyperclass가 속도를 늦춰야 할 때만 반환하세요. 위에서 설명한 재시도 흐름을 트리거합니다.
* **408 Request Timeout** – 서버가 시간 내에 호출을 처리할 수 없다는 선택적 신호입니다.
* **5xx Server Errors** – 서버 측의 하드 실패를 나타냅니다. 추가 재시도가 이루어지지 않습니다.

***

## 자주 묻는 질문

**Q: Hyperclass가 재시도 간에 이벤트를 중복 제거하나요?**

예. 각 웹훅 시도는 동일한 deliveryId 헤더를 사용하므로 중복을 안전하게 무시할 수 있습니다.

**Q: 재시도 간격이나 시도 횟수를 사용자 정의할 수 있나요?**

현재는 불가능합니다. 10분 / 6회 시도 일정은 전역적으로 적용됩니다.

**Q: 재시도가 API의 기존 속도 제한을 준수하나요?**

예—지터와 10분 지연이 급증을 최소화하지만, 이벤트당 최대 6번의 추가 호출을 예산에 포함해야 합니다.

**Q: 엔드포인트가 404나 400을 반환하면 어떻게 되나요?**

Hyperclass는 429가 아닌 응답을 최종으로 처리합니다. 추가 재시도가 발생하지 않습니다.

**Q: 스테이징 환경에서 이것을 어떻게 테스트하나요?**

스테이징 엔드포인트에서 모의 429 응답을 반환하고 Hyperclass가 약 70분에 걸쳐 페이로드를 6번 재전송하는지 확인하세요.

**Q: 워크플로우 "인바운드 웹훅(Inbound Webhook)" 트리거에 영향을 주나요?**

아니요. 자동 재시도는 Hyperclass에서 외부 서버로 전송되는 마켓플레이스 앱 웹훅에만 적용됩니다.

**Q: 과거 전송 로그를 어디서 볼 수 있나요?**

웹훅 대시보드(출시 예정)에서 시도별 로그를 확인할 수 있습니다. 그 전까지는 자체 서버 로그에 의존하세요.

**Q: 페이로드 크기 제한이 있나요?**

예—마켓플레이스 웹훅은 256KB로 제한됩니다. 더 큰 페이로드는 payloadTooLarge 플래그와 함께 잘립니다.

**Q: 어떻게 옵트아웃하나요?**

재시도 로직은 내장되어 있으며 앱별로 비활성화할 수 없습니다. 멱등성을 처리하도록 엔드포인트를 설계하세요.

**Q: Hyperclass가 5xx 오류를 재시도하나요?**

아니요—5xx 응답은 내부 서버 오류를 나타냅니다. Hyperclass는 추가 부하 없이 조사할 수 있도록 즉시 중지합니다.

***

*원문 최종 수정: Sat, 29 Nov, 2025 at 3:28 PM* *Hyperclass 사용 가이드 — hyperclass.ai*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hyperclass.gitbook.io/hyperclass-docs/app-marketplace/how-to-use-the-ai-agent-marketplace-templates-for-conversation-ai-and-voice-ai-a/automated-webhook-retries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.