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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# 예약 실행

> 호스팅된 앱의 코드를 cron에 따라 슬롯당 한 번 또는 모든 설치마다 한 번씩 실행하세요.

예약 실행은 요청에 대한 응답이 아니라 cron에 따라 호스팅된 앱을 호출합니다. 15분마다 다른 시스템에서 새 주문을 가져오거나 밤사이에 지급을 조정하는 것처럼, Whop 이벤트가 트리거하지 않는 작업에 사용하세요.

## 일정 설정

앱에는 두 가지 일정이 있습니다. [앱 업데이트](https://docs.whop.com/ko/api-reference/apps/update-app.md)로 둘 중 하나 또는 둘 다 설정하세요:

```bash theme={null}
curl -X PATCH "https://api.whop.com/api/v1/apps/app_XXXXXXXX" \
  -H "Authorization: Bearer $WHOP_DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "0 3 * * *",
    "per_install_schedule": "*/15 * * * *"
  }'
```

| 필드 | 실행 |
| - | - |
| `schedule` | 앱 전체에 대해 슬롯당 한 번 실행됩니다. |
| `per_install_schedule` | 앱을 설치한 모든 계정에 대해 슬롯당 한 번씩 실행됩니다. 각 실행에는 해당 설치 정보가 포함됩니다. 15분보다 자주 실행될 수 없습니다. |

두 필드 모두 UTC로 해석되는 최대 64자의 5필드 cron 표현식을 받습니다. 표현식은 최소 한 번은 실행되어야 합니다. `schedule`에는 최소 간격이 없습니다. 일정을 지우려면 `null` 또는 빈 문자열을 보내세요. 잘못된 표현식은 `400`을 반환합니다. 키에는 앱을 소유한 계정에 대한 `developer:update_app` 권한이 필요합니다.

## 실행 처리

빌드의 서버 엔트리에서 `fetch()` 옆에 `scheduled()`를 내보내세요:

```typescript src/server.ts theme={null}
export default {
  async fetch(request, env, ctx) {
    /* ... */
  },

  async scheduled(controller, env, ctx) {
    const { kind, app_installation } = ctx.props;

    if (kind === "global") {
      await reconcilePayouts();
      return;
    }

    await syncOrders(app_installation.external_id, app_installation.metadata.orders_cursor);
  },
};
```

`ctx.props`는 어떤 실행인지를 알려줍니다:

| 속성 | 값 |
| - | - |
| `kind` | `schedule` 실행이면 `global`, `per_install_schedule` 실행이면 `install`입니다. |
| `app_installation` | [앱 설치](https://docs.whop.com/ko/api-reference/app-installations/app-installation) 객체 형식의 설치 정보입니다. `global` 실행에서는 `null`입니다. |
| `run_id` | 이 슬롯 실행의 ID입니다. 같은 슬롯에 있는 모든 설치의 실행이 이 ID를 공유합니다. |
| `scheduled_at` | 실행 대상 슬롯으로, ISO 8601 타임스탬프 형식입니다. |
| `attempt` | 첫 시도에서는 `1`, 재시도에서는 `2`입니다. |

`controller.cron`은 실행을 예약한 표현식이고, `controller.scheduledTime`은 에포크 이후의 밀리초로 표시된 슬롯입니다.

실행은 요청 핸들러와 동일한 isolate를 사용하므로 시크릿과 [주입된 API 키](https://docs.whop.com/ko/developer/websites/hosting.md#call-the-whop-api)가 동일하게 작동합니다. 요청 핸들러는 30초가 주어지는 반면, 실행은 최대 15분까지 지속될 수 있습니다.

> [!TIP]
>
> [앱 설치](https://docs.whop.com/ko/developer/guides/app-installations.md)에서 설명한 대로 설치별 동기화 커서를 설치의 `metadata`에 보관하세요. 각 실행은 `ctx.props.app_installation.metadata`에서 이를 읽고 완료되면 새 값을 다시 기록합니다.

## 재시도 및 반복 실행

실행이 실패하면 Whop은 1분 후에 한 번 재시도한 다음 해당 실행을 폐기합니다. 재시도를 건너뛰려면 예외를 던지기 전에 `controller.noRetry()`를 호출하세요. 재시도 시 `attempt`는 `2`이며 `scheduled_at`은 여전히 원래 슬롯입니다.

같은 슬롯이 앱에 두 번 이상 도달할 수 있으며, 다음 슬롯의 실행이 이미 진행 중일 때 재시도가 시작될 수도 있습니다. 작업이 두 번 실행되면 안 되는 경우, 완료한 각 실행을 `run_id`와 `app_installation.id` 기준으로 기록하고 이미 기록된 실행은 건너뛰세요.

## 건너뛴 슬롯

앱에 서버 엔트리가 있는 프로덕션 웹 빌드가 없는 동안에는 실행이 발생하지 않습니다. Whop은 건너뛴 슬롯을 대기열에 넣거나 나중에 보충하지 않으므로, 각 실행이 마지막 실행에서 저장한 지점부터 이어서 진행하도록 만드세요.

## 로그

실행의 `console` 출력과 처리되지 않은 오류는 요청과 함께 앱의 [로그](https://docs.whop.com/ko/developer/websites/hosting.md#logs)에 표시됩니다.

## 다음 단계

> [card] [앱 설치](https://docs.whop.com/ko/developer/guides/app-installations.md)
>
> 설치별 실행에 포함되는 설치 정보와 동기화 커서를 보관할 위치입니다.

> [card] [호스팅](https://docs.whop.com/ko/developer/websites/hosting.md)
>
> 빌드, 시크릿, 주입된 API 키 및 로그.


## Related topics

- [Whop의 웹사이트 호스팅](https://docs.whop.com/ko/developer/websites/hosting.md)
- [멤버십](https://docs.whop.com/ko/developer/guides/memberships.md)
- [샌드박스에서 테스트하기](https://docs.whop.com/ko/developer/guides/sandbox.md)
