Using Dispatch

what makes a valid fireAt

An ISO 8601 timestamp in UTC with a trailing Z — 2026-06-13T09:30:00Z. Offsets like +05:30are rejected with a 400, and so is any timestamp that isn't in the future. Dispatch arms the timer for the exact millisecond, so send the moment you mean, not a rounded-down minute.

what payload is for

Whatever JSON you put in payloadcomes back verbatim in the delivery body when the job fires. Use it to carry the context your handler needs — a user ID, a plan name — so the handler doesn't have to look anything up to know what the moment means. If you omit it, the delivery carries {}.

what happens after you post

The job is written to the database and a timer is armed for fireAt. The 201 response returns the full job object — keep data.id if you might cancel later. From there the job sits in SCHEDULED until it fires; you can watch it in the dashboard the whole way.

cancelling a job that already fired

If the job is in any other state — already SUCCESS, mid-retry in FAILED, DEAD, or even FIRING at that instant — the request returns a 400 and changes nothing:

{
  "status": false,
  "message": "Only scheduled jobs can be cancelled",
  "data": null
}

A 404 means the job ID doesn't exist or belongs to a different project than the key you used.

headers

POST /hooks/trial-expiry HTTP/1.1
Content-Type: application/json

Content-Type: application/json is the only header Dispatch sets. There is no signature header yet — see verifying the sender for the interim approach.

the response dispatch expects

Return any 2xx to mark the delivery SUCCESS. Any other status — or a connection error — marks it FAILED and schedules a retry. Whatever body your endpoint returns is captured in the delivery log, so a short diagnostic string is worth returning; it is what you will read in the dashboard when something breaks.

retries

The retry clock is fixed: 30 seconds after the first failure, 1 minute after the second, 5 minutes as the configured ceiling — and a job is marked DEAD on its third failed attempt. Every attempt is logged with its status code, response body, and timing.

scheduling a job

// dispatch.js — Node 18+, no SDK needed
const DISPATCH_URL = process.env.DISPATCH_URL ?? "https://api-dispatch.imtiyazsayyid.in";
const DISPATCH_API_KEY = process.env.DISPATCH_API_KEY; // sk_...
 
export async function scheduleJob({ title, webhookUrl, fireAt, payload }) {
  const res = await fetch(`${DISPATCH_URL}/api/v1/jobs`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": DISPATCH_API_KEY,
    },
    body: JSON.stringify({
      title,
      webhookUrl,
      fireAt: fireAt.toISOString(), // UTC with trailing Z — required
      payload,
    }),
  });
 
  const body = await res.json().catch(() => null);
  if (!res.ok || !body?.status) {
    throw new Error(body?.message ?? `Dispatch returned ${res.status}`);
  }
  return body.data; // the created job — keep data.id if you may cancel it
}
 
const job = await scheduleJob({
  title: "Trial expiry reminder",
  webhookUrl: "https://your-app.com/hooks/trial-expiry",
  fireAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
  payload: { userId: "usr_812" },
});
console.log(`scheduled ${job.id}, fires at ${job.fireAt}`);

handling the webhook

The contract is simple: return any 2xx and the delivery is SUCCESS; return anything else — or be unreachable — and Dispatch retries with backoff. Two rules follow from it: respond before you do the heavy work, and make your handler idempotent, because retries mean a delivery can arrive more than once.

// server.js — Express
import express from "express";
 
const app = express();
app.use(express.json());
 
app.post("/hooks/trial-expiry", (req, res) => {
  const { jobId, title, payload, firedAt } = req.body;
 
  // Acknowledge with a 2xx first — anything else (including a crash or
  // a slow handler) makes Dispatch retry, so do the heavy work after.
  res.status(200).json({ received: true });
 
  setImmediate(async () => {
    try {
      // Retries mean at-least-once delivery: use jobId as an idempotency
      // key so a retried delivery can't send the email twice.
      await sendTrialExpiryEmail(jobId, payload.userId);
    } catch (err) {
      console.error(`hook ${jobId} (${title}) failed:`, err);
    }
  });
});
 
app.listen(5000);

verifying the sender

# Planned delivery headers — NOT sent yet:
#
#   x-dispatch-signature: t=1765703400,v1=<hex hmac-sha256>
#
# where v1 = HMAC-SHA256(project_signing_secret, "{t}.{raw_body}").
# Verification will be: recompute the HMAC over the exact raw body,
# compare in constant time, and reject timestamps older than ~5 minutes.

In the meantime, don't accept anonymous POSTs: put a secret in the webhook URL when you schedule, and check it on receipt. It's not a signature, but it stops drive-by requests cold.

// Until signatures ship: schedule with a long random token in the URL...
//   webhookUrl: "https://your-app.com/hooks/trial-expiry?token=" + WEBHOOK_TOKEN
// ...and verify it on every delivery, in constant time.
 
import { timingSafeEqual } from "node:crypto";
 
function verifyToken(req) {
  const token = Buffer.from(String(req.query.token ?? ""));
  const expected = Buffer.from(process.env.WEBHOOK_TOKEN);
  return token.length === expected.length && timingSafeEqual(token, expected);
}

base url

https://api-dispatch.imtiyazsayyid.in/api/v1

Dispatch is a hosted service — that base URL is all you need. (Running your own instance instead? The API is identical; swap in your own origin and see the self-hosting guide.)

Every response — success or error — uses the same envelope. On errors, status is false and messagesays why, alongside the HTTP status code (400 for validation, 401 for bad credentials, 404 for resources that aren't yours).

{
  "status": true,            // false on any error
  "message": "Job scheduled successfully",
  "data": { ... }            // the resource, or null
}