Skip to main content
Posthook supports three ways to schedule a hook: a UTC timestamp (postAt), a local datetime with a timezone (postAtLocal + timezone), or a relative delay from now (postIn).

​
UTC scheduling with postAt

Provide an RFC 3339 timestamp in UTC: 
const hook = await posthook.hooks.schedule({
  path: '/webhooks/reminder',
  postAt: '2026-03-14T18:00:00Z',
  data: { user_id: 'usr_123' }
});
FieldDescription
postAtRFC 3339 timestamp in UTC (e.g., 2026-03-14T18:00:00Z). Timestamps in the past are delivered immediately.

​
Local time scheduling with postAtLocal + timezone

When you need delivery at a specific clock time in a specific timezone, use postAtLocal and timezone together. Posthook converts the local time to UTC at scheduling time, accounting for DST. 
const hook = await posthook.hooks.schedule({
  path: '/webhooks/reminder',
  postAtLocal: '2026-03-15T09:00:00',
  timezone: 'America/New_York',
  data: { user_id: 'usr_123' }
});
FieldDescription
postAtLocalISO 8601 local datetime without offset, in YYYY-MM-DDTHH:MM:SS format (e.g., 2026-03-15T13:00:00). Do not include a Z suffix or UTC offset.
timezoneIANA Time Zone identifier (e.g., America/New_York, Europe/London, Asia/Tokyo).

​
Relative delay with postIn

Schedule a hook relative to now using a duration string. Posthook resolves the delay to a UTC timestamp at scheduling time. 
const hook = await posthook.hooks.schedule({
  path: '/webhooks/process',
  postIn: '1h30m',
  data: { job_id: 'job_789' }
});
FieldDescription
postInDuration string specifying how far in the future to deliver. Uses unit suffixes: d (days), h (hours), m (minutes), s (seconds). Compound values like 1d2h30m are supported. Minimum 1 second, maximum 365 days.
Examples: 30s, 5m, 2h, 7d, 1h30m, 1d2h30m45s

​
Validation rules

  • Provide exactly one of postAt, postAtLocal, or postIn.
  • timezone is required with postAtLocal and forbidden with postAt or postIn.

​
DST behavior

When using postAtLocal + timezone, Posthook resolves ambiguous times automatically:
  • Spring forward (gap): If the local time falls in a skipped hour, delivery is shifted forward to the first valid moment after the gap (e.g., 02:30 becomes 03:00).
  • Fall back (fold): If the local time occurs twice, the earlier occurrence is used.

​
Per-hook retry override

You can override your project’s default retry settings for individual hooks by including a retryOverride object. If omitted, the hook uses your project’s retry configuration.

​
Fields

FieldTypeRequiredDescription
minRetriesintegerYesNumber of retry attempts (1–15)
delaySecsintegerYesBase delay between retries in seconds (5–60)
strategystringYesfixed (constant delay) or exponential (increasing delay). Available strategies may vary by plan.
backoffFactornumberNoMultiplier for exponential backoff (1.1–4.0). Defaults to 2.0 if omitted.
maxDelaySecsintegerNoMaximum delay cap in seconds (60–3600). Required when strategy is exponential.
jitterbooleanNoAdd random jitter to retry delays to avoid thundering herd

​
Example: aggressive retries

Retry up to 15 times with a 5-second fixed delay: 
const hook = await posthook.hooks.schedule({
  path: '/webhooks/process-payment',
  postAt: '2026-03-14T18:00:00Z',
  data: { order_id: 'ord_789' },
  retryOverride: {
    minRetries: 15,
    delaySecs: 5,
    strategy: 'fixed'
  }
});

​
Example: exponential backoff

Start with a 10-second delay, doubling up to 5 minutes: 
const hook = await posthook.hooks.schedule({
  path: '/webhooks/sync-data',
  postAtLocal: '2026-03-15T09:00:00',
  timezone: 'America/Chicago',
  data: { sync_id: 'sync_456' },
  retryOverride: {
    minRetries: 8,
    delaySecs: 10,
    strategy: 'exponential',
    backoffFactor: 2.0,
    maxDelaySecs: 300,
    jitter: true
  }
});

​
Usage quota

Each plan includes a monthly hook quota — the number of hooks you can schedule per calendar month. Every POST /hooks call counts toward the quota, regardless of when the hook is scheduled to deliver. The quota resets at the start of each calendar month. When you hit the limit, POST /hooks returns 429 Too Many Requests until the quota resets. Posthook sends email alerts at 75%, 100%, and 150% of your quota so you can adjust usage or upgrade before reaching the limit. Quota limits may vary by plan.

​
Quota headers

Every POST /hooks response includes headers showing your current plan usage:
HeaderDescription
Posthook-HookQuota-LimitMaximum hooks allowed in the current calendar month
Posthook-HookQuota-UsageHooks used so far in the current calendar month
Posthook-HookQuota-RemainingHooks remaining in the current calendar month
Posthook-HookQuota-Resets-AtRFC 3339 timestamp when the quota resets
Use these headers to monitor usage programmatically and avoid hitting plan limits.