> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook FAQ

> Webhook 관리, 네트워크 지원, 재시도 및 문제 해결 등에서 가장 흔한 질문에 대한 답변을 얻으세요.

## 크레딧 및 속도 제한

<Accordion title="1개의 웹훅에 몇 개의 주소를 입력할 수 있나요?">
  [API](/docs/ko/api-reference/webhooks/create-webhook)를 사용하여 최대 100,000개의 주소를 입력할 수 있습니다.
</Accordion>

<Accordion title="웹훅을 생성한 후 Helius 대시보드에서 웹훅 URL을 변경하면 크레딧이 차감되나요?">
  네, API 또는 대시보드를 통해 웹훅을 편집하면 요청당 100크레딧이 소모됩니다. URL 변경, 주소 추가/제거, 트랜잭션 유형 업데이트 등의 모든 수정에 적용됩니다.
</Accordion>

<Accordion title="웹훅 알림을 받을 때 크레딧이 얼마나 소모되나요?">
  Helius가 이벤트를 처리하여 엔드포인트로 보낼 때마다 각 웹훅 이벤트가 1크레딧을 소모합니다. 엔드포인트가 웹훅을 성공적으로 처리했는지 오류를 반환했는지에 관계없이 요금이 부과됩니다.
</Accordion>

<Accordion title="웹훅을 생성, 편집, 삭제할 때 비용은 얼마인가요?">
  API를 통해 수행될 때 모든 웹훅 관리 작업(생성, 편집, 삭제)은 요청당 100크레딧이 소모됩니다. 이는 웹훅 설정을 업데이트하는 데 필요한 처리를 포함합니다.
</Accordion>

## 지원되는 네트워크

<Accordion title="솔라나 Devnet에서 웹훅을 사용할 수 있나요?">
  네. UI를 통해 웹훅을 생성할 경우, "Network"로 "devnet"을 선택하세요. Webhook API를 통해 생성할 경우 "webhookType" 매개변수를 원하는 웹훅 유형에 따라 "rawDevnet", "enhancedDevnet" 또는 “discordDevnet”으로 설정하세요.
</Accordion>

<Accordion title="웹훅 URL로 'localhost'를 입력할 수 있나요?">
  아니요—URL은 HTTPS를 통해 공개적으로 접근 가능해야 합니다. Helius는 localhost URL을 통해 로컬 개발 서버에 접근할 수 없습니다.
</Accordion>

## 웹훅 사용

<Accordion title="웹훅이 Helius에서 온 것인지 어떻게 확인할 수 있나요?">
  웹훅을 생성하거나 업데이트할 때 승인 헤더를 설정하세요. Helius는 데이터를 웹훅 엔드포인트로 전송할 때 이 값을 `Authorization` 헤더에 반영하여 요청의 진위를 확인할 수 있습니다.
</Accordion>

<Accordion title="'raw'와 'enhanced' 웹훅의 차이점은 무엇인가요?">
  **Raw 웹훅**은 Solana 트랜잭션 데이터를 블록체인에서 직접 반환합니다. 모니터링 중인 주소에서 트랜잭션이 발생할 때 원시 트랜잭션 데이터가 웹훅 URL로 전송됩니다.

  **Enhanced 웹훅**은 Helius의 해석된 트랜잭션 유형을 제공합니다. 우리는 (NFT 상장, DeFi 스왑, 송금 등) 100가지가 넘는 Solana 트랜잭션 유형을 분석하고 이를 자체 스키마로 추상화합니다.

  추상화 없이 모든 트랜잭션 데이터를 원할 경우 raw 웹훅을 사용하고, 내장된 트랜잭션 유형 탐지 및 분석을 원할 경우 enhanced 웹훅을 사용하세요.
</Accordion>

<Accordion title="웹훅이 언제 알림을 보내나요?">
  웹훅은 블록체인에서 일치하는 트랜잭션이 확인된 직후에 알림을 보냅니다.
</Accordion>

## 재시도

<Accordion title="웹훅 이벤트를 어떻게 확인해야 하나요?">
  엔드포인트는 성공적인 수신을 확인하기 위해 **1초** 이내에 `200` 상태 코드를 반환해야 합니다. 최선의 방법은 즉시 `200`로 응답하고, 모든 처리는 비동기적으로 처리하는 것입니다 — 이는 느린 비즈니스 로직으로 인한 타임아웃을 방지합니다.
</Accordion>

<Accordion title="웹훅의 재시도 정책은 무엇인가요?">
  Helius는 당신의 엔드포인트가 `5xx` 오류, `4xx` 오류 (`403` 제외), 타임아웃, 또는 연결 오류나 DNS 실패로 인해 실패할 경우 전송을 재시도합니다. 우리는 **3번**까지 **1초 간격**으로 재시도합니다.

  모든 재시도 시도가 실패할 경우, 이벤트는 **영구적으로 손실**됩니다 — 재큐 또는 두 번째 전송 주기가 없습니다.

  [Helius 대시보드](https://dashboard.helius.dev/webhooks)에서 웹훅 로그를 모니터링하여 전송 실패를 식별하고 엔드포인트 문제를 조사하세요.

  기업 플랜에는 사용자 정의 가능한 재시도 정책도 제공합니다.
</Accordion>

<Accordion title="웹훅 이벤트는 한 번만 전송되나요?">
  Helius는 동일한 웹훅 이벤트를 여러 번 전송할 수 있습니다. 이는 재시도 로직이나 네트워크 문제로 인해 발생할 수 있습니다.

  웹훅 핸들러는 중복을 우아하게 처리할 준비가 되어 있어야 합니다 — 동일한 이벤트를 여러 번 처리하더라도 한 번 처리한 것과 동일한 결과를 생성해야 합니다.

  중복 처리를 위해, 트랜잭션 서명이나 고유한 이벤트 식별자를 사용하여 이미 처리한 이벤트를 추적하세요.
</Accordion>

<Accordion title="실패한 트랜잭션도 웹훅으로 전송되나요?">
  웹훅 유형에 따라 다릅니다. Enhanced 웹훅은 실패한 트랜잭션을 전송하지 않지만, raw 웹훅은 성공한 트랜잭션과 실패한 트랜잭션 모두를 포함합니다.
</Accordion>

## 자동 비활성화

<Accordion title="왜 내 웹훅이 자동으로 비활성화되었나요?">
  Helius는 엔드포인트 상태를 모니터링하며 **≥ 95% 전송 실패율**을 가진 웹훅을 자동으로 비활성화합니다. 유료 플랜(Dev 및 이상)은 7일 동안 평가되며, 무료 플랜 웹훅은 24시간 동안 평가됩니다. 이는 도달 불가능한 엔드포인트에 대한 불필요한 전송 시도를 방지합니다.

  일반적인 원인은 도달 불가능한 엔드포인트 URL, 일관된 오류 응답을 반환하는 서버, Helius 전송을 차단하는 네트워크/방화벽 문제 등이 있습니다.
</Accordion>

<Accordion title="비활성화된 웹훅을 어떻게 다시 활성화하나요?">
  1. 엔드포인트의 근본적인 문제를 해결하세요.
  2. [Helius 대시보드](https://dashboard.helius.dev/webhooks)에 로그인하세요.
  3. 비활성화된 웹훅을 찾아 다시 활성화하세요.

  또한, `{ "active": true }`를 사용하여 PATCH 요청을 보내 [Toggle Webhook API 엔드포인트](/docs/ko/api-reference/webhooks/toggle-webhook)를 통해 프로그램적으로 웹훅을 다시 활성화할 수 있습니다.
</Accordion>

<Accordion title="다시 활성화한 직후에 웹훅이 다시 비활성화될까요?">
  아니요. 다시 활성화한 후 웹훅은 **24시간의 유예 기간**에 들어가며 이 기간 동안 자동으로 비활성화되지 않습니다. 이는 다음 평가 전에 엔드포인트가 정상인지 확인할 시간을 제공합니다.
</Accordion>

<Accordion title="웹훅이 자동으로 비활성화되면 알림을 받을 수 있나요?">
  네 — **Dev 플랜 이상**의 사용자는 웹훅이 자동으로 비활성화될 때 이메일 알림을 받습니다. 무료 플랜 사용자는 [Helius 대시보드](https://dashboard.helius.dev/webhooks)에서 웹훅 상태를 모니터링할 수 있습니다.
</Accordion>

<Accordion title="웹훅을 삭제하지 않고 비활성화할 수 있나요?">
  네. [Helius 대시보드](https://dashboard.helius.dev/webhooks) 또는 [Toggle Webhook API 엔드포인트](/docs/ko/api-reference/webhooks/toggle-webhook)를 통해 웹훅을 켜고 끌 수 있습니다. 이를 통해 웹훅 구성을 잃지 않고 전송을 일시적으로 중지할 수 있습니다.
</Accordion>

## 웹훅 문제 해결

<Accordion title="내 웹훅이 데이터를 누락하는 이유는 무엇인가요?">
  데이터 누락은 일반적으로 엔드포인트에서 오류가 발생하여 웹훅 재시도가 결국 실패하고 데이터가 손실될 때 발생합니다. [대시보드](https://dashboard.helius.dev/webhooks)에서 웹훅 로그를 확인하고, 충분한 클라이언트 측 로그가 있는지 확인하며 문제가 지속되면 [지원 팀에 문의하세요](/docs/ko/support/contact-support).
</Accordion>

<Accordion title="왜 내 웹훅이 작동하지 않나요?">
  선택한 트랜잭션 유형이 모니터링 중인 트랜잭션과 일치하는지 확인하세요. 일반적인 문제인지 유형 불일치인지 식별하기 위해 "ANY" 트랜잭션 유형으로 시작하세요. 문제점이 엔드포인트 설정에 있는지를 테스트하기 위해 [webhook.site](http://webhook.site/)를 사용하세요.
</Accordion>

<Accordion title="특정 유형의 모든 트랜잭션(예: TOKEN_MINT)을 내 웹훅이 왜 보내지 않나요?">
  `TOKEN_MINT` 웹훅은 Candy Machine V1, Solana Program Library와 같은 특정 프로그램에만 트리거됩니다. 블록체인 전체의 모든 토큰 발행 이벤트를 포괄하지 않습니다. 더 넓은 모니터링을 위해 "ANY" 트랜잭션 유형 필터링이 있는 웹훅을 통해 더 일반적인 계정 또는 프로그램 구독을 고려하세요.
</Accordion>

***

## 도움이 더 필요하신가요?

<CardGroup cols={2}>
  <Card title="지원 문의" icon="headset" href="/docs/ko/support/contact-support">
    Discord, 채팅, 이메일 지원을 통해 저희 팀의 도움을 받으세요.
  </Card>

  <Card title="상태 페이지" icon="wave-pulse" href="/docs/ko/support/status-page">
    실시간 서비스 가용성 및 성능 정보를 확인하세요.
  </Card>
</CardGroup>