Skip to main content
POST
/
hooks
Schedule Hook
curl --request POST \
  --url https://api.posthook.io/v1/hooks \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "path": "/webhooks/reminder",
  "data": {
    "user_id": "123"
  },
  "postAt": "2026-03-14T12:00:00Z",
  "postAtLocal": "2026-03-15T13:00:00",
  "timezone": "America/New_York",
  "postIn": "1h30m",
  "retryOverride": {
    "minRetries": 8,
    "delaySecs": 32,
    "strategy": "fixed",
    "backoffFactor": 2.55,
    "maxDelaySecs": 1830,
    "jitter": true
  }
}
'
{
  "data": {
    "id": "<string>",
    "path": "<string>",
    "domain": "<string>",
    "data": {},
    "postAt": "2023-11-07T05:31:56Z",
    "status": "pending",
    "postDurationSeconds": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "attempts": 123,
    "failureError": "<string>",
    "tryAt": "2023-11-07T05:31:56Z",
    "wasNotified": true,
    "sequenceData": {
      "sequenceID": "<string>",
      "stepName": "<string>",
      "sequenceLastRunAt": "2023-11-07T05:31:56Z"
    }
  }
}
Schedule a new webhook to be sent at a specific time in the future (or immediately).
Pro Tip: To verify immediate delivery, use a timestamp in the past (e.g. yesterday).

​
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: Schedule event reminders and abandoned cart recovery emails.
  • Auto-Expiry (TTL): Schedule the deletion of temporary resources (e.g. shared links) at the moment of creation.
  • Recursive Polling: Periodically check a long-running job (e.g. video encoding) until it completes.
  • Debouncing: Prevent duplicate processing by verifying event freshness.

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
path
string
required

The endpoint path for delivery.

Example:

"/webhooks/reminder"

​
data
object
required

Arbitrary JSON payload delivered with the hook.

Example:
{ "user_id": "123" }
​
postAt
string<date-time>

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
string

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
string

IANA Time Zone identifier (e.g. America/New_York). Required when using postAtLocal. Forbidden with postAt and postIn.

Example:

"America/New_York"

​
postIn
string

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"

​
retryOverride
object

Per-hook retry configuration. Overrides the project's default retry settings for this hook.

Response

201 - application/json

Hook scheduled

​
data
object