DocsSchedule Webhooks API

API reference

Schedule a webhook with one API call

Create delayed HTTPS jobs from your backend, retry failed deliveries, and inspect every scheduled webhook from the dashboard.

Create free API key Try in browser

Base URL

https://webhookscheduler.com

Authentication

Public API calls require an API key created from the dashboard. Send it as eitherAuthorization: Bearer YOUR_KEY or x-api-key: YOUR_KEY.

Headers

Authorization: Bearer wh_live_xxxxxxxxx
Content-Type: application/json

Schedule a webhook

POST/api/v1/schedule

Creates a future delivery. The target must be HTTPS and public; private networks, localhost, metadata endpoints, and unsafe redirects are blocked.

Request body

urlstringrequired

Destination HTTPS URL.

methodstring

One of GET, POST, PUT, PATCH, DELETE. Default is POST.

bodyjson

JSON payload sent to the destination. Alias: payload.

headersobject

Custom user headers. Unsafe hop-by-hop or proxy headers are stripped before dispatch.

runAtISO date stringrequired

Future execution time.

idempotencyKeystring

Optional key to avoid creating duplicate jobs for the same organization.

cURL

curl https://webhookscheduler.com/api/v1/schedule \
  -H "Authorization: Bearer wh_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhook",
    "method": "POST",
    "body": { "event": "user.created" },
    "runAt": "{{ tomorrow_at_09_utc }}",
    "idempotencyKey": "user-created-123"
  }'

Response

201 Created

{
  "id": "job_...",
  "status": "PENDING",
  "scheduledFor": "{{ tomorrow_at_09_utc }}",
  "idempotencyKey": "user-created-123"
}

Execute immediately

POST/api/v1/execute-now

Dispatches a webhook immediately using the same SSRF policy and header sanitization as scheduled jobs.

urlstringrequired

Destination HTTPS URL.

methodstring

One of GET, POST, PUT, PATCH, DELETE. Default is POST.

headersobject

Optional headers after sanitization.

bodyjson

Optional JSON request body.

cURL

curl https://webhookscheduler.com/api/v1/execute-now \
  -H "Authorization: Bearer wh_live_xxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhook",
    "body": { "event": "manual.test" }
  }'

Response

200 OK

{
  "success": true,
  "status": 200,
  "data": { "ok": true },
  "durationMs": 143
}

Webhook signatures

Each outgoing delivery can include a Webhook-Signature header signed with the workspace secret from Settings. Rotate the secret once, store it server-side, then verify the timestamp and HMAC on your receiver before trusting the payload.

Header

Webhook-Signature: t=1780732800,v1=hex_hmac_sha256

Node.js verification

import crypto from "node:crypto";

const header = req.headers["webhook-signature"];
const parts = Object.fromEntries(
  header.split(",").map(part => part.split("="))
);

const payloadToSign = `${parts.t}.${rawBody}`;
const expected = crypto
  .createHmac("sha256", process.env.WEBHOOK_SCHEDULER_SECRET)
  .update(payloadToSign)
  .digest("hex");

if (!crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))) {
  throw new Error("Invalid webhook signature");
}

Job statuses

PENDING

Scheduled and waiting for delivery.

PROCESSING

The delivery is currently being sent.

SUCCESS

Delivered successfully.

FAILED

Final failure after all retries or unrecoverable scheduling failure.

RETRYING

Failed once and scheduled for the next recovery attempt.

CANCELED

Canceled before delivery.

Errors

400

Validation failed or unsafe target URL. SSRF failures return code UNSAFE_TARGET_URL.

401

Missing or invalid API key.

403

Plan quota exceeded.

405

Unsupported HTTP method.

429

Rate limit exceeded.

500

Internal error. Retry later with backoff.

Security model

Outbound webhooks are HTTPS-only and revalidated immediately before dispatch.

Redirects are not followed automatically. A 3xx response from your endpoint is recorded as the webhook result.

DNS lookups are pinned to the validated public IP to reduce DNS rebinding risk.

Outbound deliveries are signed with Webhook-Signature when the workspace has a signing secret.

Each scheduled job is claimed once before delivery to reduce duplicate sends.

For the complete target validation, retry, timeout, retention, and abuse-control model, read Security and reliability.