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

# Schedule Hook

> Schedule a new hook for delivery at a specific time. Supports UTC, local-time, and relative-delay scheduling modes.

Schedule a new webhook to be sent at a specific time in the future (or immediately).

<Tip>
  **Pro Tip**: To verify immediate delivery, use a timestamp in the past (e.g. yesterday).
</Tip>

## URL Resolution

When you schedule a hook, you provide a `path` (e.g. `/webhooks/remind`).

Posthook constructs the full destination URL by combining your **Project Domain** with this `path`.

> **Destination URL** = `Project Domain` + `path`

For example, if your Project Domain is `api.myapp.com` and you schedule a hook with path `/webhooks/payment`, we will POST to `https://api.myapp.com/webhooks/payment` (Posthook enforces HTTPS).

## Usage Patterns

* [**User Engagement**](/patterns/user-engagement): Schedule event reminders and abandoned cart recovery emails.
* [**Auto-Expiry (TTL)**](/patterns/auto-expiry): Schedule the deletion of temporary resources (e.g. shared links) at the moment of creation.
* [**Recursive Polling**](/patterns/polling): Periodically check a long-running job (e.g. video encoding) until it completes.
* [**Debouncing**](/patterns/debouncing): Prevent duplicate processing by verifying event freshness.


## OpenAPI

````yaml POST /hooks
openapi: 3.0.0
info:
  title: Posthook API
  version: 1.0.0
  description: >-
    REST API for scheduling, managing, and inspecting durable webhook
    deliveries.
servers:
  - url: https://api.posthook.io/v1
security:
  - apiKey: []
paths:
  /hooks:
    post:
      summary: Schedule Hook
      description: >-
        Schedule a new hook for delivery at a specific time. Supports UTC,
        local-time, and relative-delay scheduling modes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - path
                - data
              properties:
                path:
                  type: string
                  description: The endpoint path for delivery.
                  example: /webhooks/reminder
                postAt:
                  type: string
                  format: date-time
                  description: >-
                    RFC 3339 timestamp in UTC for delivery. Mutually exclusive
                    with `postAtLocal` + `timezone`. Timestamps in the past are
                    delivered immediately.
                  example: '2026-03-14T12:00:00Z'
                postAtLocal:
                  type: string
                  description: >-
                    ISO 8601 local datetime without offset, in
                    YYYY-MM-DDTHH:MM:SS format (e.g. `2026-03-15T13:00:00`).
                    Must be used with `timezone`. Mutually exclusive with
                    `postAt`.
                  example: '2026-03-15T13:00:00'
                timezone:
                  type: string
                  description: >-
                    IANA Time Zone identifier (e.g. `America/New_York`).
                    Required when using `postAtLocal`. Forbidden with `postAt`
                    and `postIn`.
                  example: America/New_York
                postIn:
                  type: string
                  description: >-
                    Relative delay from now as a duration string (e.g., `5m`,
                    `2h`, `1d12h`). Units: `d` (days), `h` (hours), `m`
                    (minutes), `s` (seconds). Min 1s, max 365d. Mutually
                    exclusive with `postAt` and `postAtLocal`. Cannot be used
                    with `timezone`.
                  example: 1h30m
                data:
                  type: object
                  description: Arbitrary JSON payload delivered with the hook.
                  example:
                    user_id: '123'
                retryOverride:
                  $ref: '#/components/schemas/RetryOverride'
      responses:
        '201':
          description: Hook scheduled
          headers:
            Posthook-HookQuota-Limit:
              description: >-
                The maximum number of hooks allowed in the current billing
                period.
              schema:
                type: integer
            Posthook-HookQuota-Usage:
              description: The number of hooks used in the current billing period.
              schema:
                type: integer
            Posthook-HookQuota-Remaining:
              description: The number of hooks remaining in the current billing period.
              schema:
                type: integer
            Posthook-HookQuota-Resets-At:
              description: RFC 3339 timestamp when the quota resets.
              schema:
                type: string
                format: date-time
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Hook'
components:
  schemas:
    RetryOverride:
      type: object
      description: >-
        Per-hook retry configuration. Overrides the project's default retry
        settings for this hook.
      properties:
        minRetries:
          type: integer
          minimum: 1
          maximum: 15
          description: Number of retry attempts (1–15).
        delaySecs:
          type: integer
          minimum: 5
          maximum: 60
          description: Delay between retries in seconds (5–60).
        strategy:
          type: string
          enum:
            - fixed
            - exponential
          description: >-
            Retry strategy. `fixed` uses a constant delay. `exponential`
            increases the delay with each attempt.
        backoffFactor:
          type: number
          minimum: 1.1
          maximum: 4
          description: >-
            Multiplier for exponential backoff (1.1–4.0). Defaults to 2.0 if
            omitted. Only used when strategy is `exponential`.
        maxDelaySecs:
          type: integer
          minimum: 60
          maximum: 3600
          description: >-
            Maximum delay between retries in seconds (60–3600). Only used when
            strategy is `exponential`.
        jitter:
          type: boolean
          description: Add random jitter to retry delays to avoid thundering herd.
      required:
        - minRetries
        - delaySecs
        - strategy
    Hook:
      type: object
      properties:
        id:
          type: string
        path:
          type: string
        domain:
          type: string
        data:
          type: object
        postAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - pending
            - completed
            - failed
            - retry
        postDurationSeconds:
          type: number
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        attempts:
          type: integer
        failureError:
          type: string
        tryAt:
          type: string
          format: date-time
        wasNotified:
          type: boolean
        sequenceData:
          $ref: '#/components/schemas/HookSequenceData'
    HookSequenceData:
      type: object
      properties:
        sequenceID:
          type: string
        stepName:
          type: string
        sequenceLastRunAt:
          type: string
          format: date-time
  securitySchemes:
    apiKey:
      type: apiKey
      name: X-API-Key
      in: header

````