Reconcile delayed jobs with the records that created them

The difficult question in delayed work is often not “when will this run?” but “what happened to the request we tried to schedule?” A business record and a scheduler job live in different systems. Reconciliation gives you a way to compare their accounts of the same intention.

Give each intention a durable record

Store the business event ID, the intended delivery time, the scheduling idempotency key and the returned job ID. Track scheduling as a state with possible uncertainty, rather than treating an outbound API call as an atomic part of your local database transaction.

Choose a reference that an operator can connect to the business record without exposing personal data. WebhookScheduler's documented reference field can be used when listing jobs. It helps investigation, but it does not replace keeping your own application record or storing the returned job ID.

Keep the scheduling request recoverable

The illustrative request below sends a stable record identifier. Your application must replace it with the actual event and save the result. A successful API response followed by a failed local write leaves a real remote job behind.

Illustrative server-side example: this schedules delivery 24 hours from execution. Replace the environment variables and example record IDs, persist the returned job ID, and implement your own authenticated HTTPS receiver. The request follows the current API reference.

const apiKey = process.env.WEBHOOK_SCHEDULER_API_KEY;
const receiverUrl = process.env.REMINDER_WEBHOOK_URL;
if (!apiKey || !receiverUrl) throw new Error("Set the server-side API key and public HTTPS receiver URL.");

const response = await fetch("https://webhookscheduler.com/api/v1/schedule", {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    url: receiverUrl,
    method: "POST",
    runAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
    reference: "record:example-123",
    idempotencyKey: "record-example-123-reminder-v1",
    body: { resourceId: "example-123" },
  }),
});
if (!response.ok) throw new Error(`Scheduling failed: ${response.status}`);
const job = await response.json();
if (!job.id) throw new Error("Missing scheduled job ID");
// Persist job.id with your business record before acknowledging this work.
console.log(job.id);

Retrying the same scheduling idempotency key can recover the retained original job. Do this before generating a fresh key. The documented API returns that original job without comparing a new payload, so this retry recovers an existing intention; it does not update its parameters.

Separate unknown from failed

An API timeout does not prove rejection. Likewise, an application error after a successful response does not remove the remote job. Keep an explicit uncertain state that a reconciliation worker or operator can revisit.

Inspect the job using its stored ID when available. Use the documented reference filter when investigating related work, and consider pagination and retention when interpreting a missing result. Do not turn “not found in this response” into an assertion that the work never existed or never ran.

Compare outcomes at the right level

A successful HTTP delivery means the receiving endpoint returned a response that the scheduler treated as successful. It is not automatically evidence that an invoice was paid, a user activated or an email reached an inbox.

Record the business outcome in the application that owns it. Authenticate deliveries and make the receiver's effect idempotent. If the effect crosses another service boundary, retain enough identity to investigate a timeout there too. Reconciliation should recover uncertainty rather than trigger an uncontrolled replay of potentially completed work.

Start with a small operations view

WebhookScheduler is built by AllClearStack. A focused scheduler can remove queue operation from the application, but it cannot interpret your business records for you. Keep the relationship between local intentions and remote jobs visible.

Begin with a list of old unresolved scheduling attempts, their business references and the next safe action. Avoid a large monitoring system until you know which decisions an operator actually needs to make. An existing database worker can perform this reconciliation if you already operate one. The workflow guides help distinguish scheduling, delivery and business-effect responsibilities.