Core concepts

Webhooks

Signed callbacks when an async job ends.

What a webhook is for

Route-scan and hopping jobs run in the background. Instead of polling GET /v1/jobs/{job_id}, give a callback_url when you submit the job, and RailCore POSTs the outcome to it once the job ends.

Ask for a callback

Add callback_url to the body of POST /v1/jobs/route-scan or POST /v1/jobs/hopping.

cURL
RUN_DATE=$(TZ=Asia/Kolkata date +%F)

curl -sS -X POST \
  -H "X-RailCore-Key: $RAILCORE_KEY" \
  -H "Content-Type: application/json" \
  --data '{"from":"BSL","to":"ADI","date":"'"$RUN_DATE"'","callback_url":"https://hooks.example.com/railcore"}' \
  "https://ir.railcore.tech/v1/jobs/route-scan"

The 202 answer carries webhook_secret. It is shown once and RailCore does not store it: save it with the job_id. It is the key that signs this job's callbacks.

JSON
{
  "success": true,
  "data": {
    "job_id": "job_01J5Z7Y8N2K4M6P8R0T2V4X6Z8",
    "status": "processing",
    "poll_url": "/v1/jobs/job_01J5Z7Y8N2K4M6P8R0T2V4X6Z8",
    "stream_url": "/v1/jobs/job_01J5Z7Y8N2K4M6P8R0T2V4X6Z8/stream",
    "message": "Route scan submitted. Poll the poll_url for results.",
    "webhook_secret": "whsec_..."
  }
}

The callback URL

  • An https URL on a public host, on port 443 or a port from 1024 up.
  • No user name or password in the URL.
  • Not localhost, and not a private, link-local, CGNAT (100.64.0.0/10) or cloud metadata address.
  • Checked when the job is submitted: a URL that breaks a rule answers 400 VALIDATION_ERROR with details[].field callback_url, and is not counted. Checked again just before each send, after the host name is resolved, so a name that later points at a private address is not called.
  • Redirects are not followed. A 3xx answer is final.

What RailCore sends

One POST with a JSON body when the job ends.

HTTP
POST /railcore HTTP/1.1
Content-Type: application/json
X-RailCore-Webhook-Id: job_01J5Z7Y8N2K4M6P8R0T2V4X6Z8
X-RailCore-Webhook-Timestamp: 1785472200
X-RailCore-Webhook-Attempt: 1
X-RailCore-Webhook-Signature: v1=5f2b...e91c

{"job_id":"job_01J5Z7Y8N2K4M6P8R0T2V4X6Z8","status":"complete","result":{ ... }}
  • The body is { "job_id", "status": "complete", "result" }, where result is what polling the job returns, or { "job_id", "status": "failed", "error" }.
  • X-RailCore-Webhook-Id is the job id. X-RailCore-Webhook-Timestamp is when this send was signed, in Unix seconds. X-RailCore-Webhook-Attempt is which send it is, 1 to 4.
  • X-RailCore-Webhook-Signature is v1= and the lower-case hex HMAC-SHA256 of the timestamp, a period and the raw body (<timestamp>.<raw body>), keyed with the job's webhook_secret.

Check the signature

Check every callback before you trust it. Sign the raw bytes you received: parsing the JSON and serializing it again changes them.

Node.js
import crypto from "node:crypto";

const TOLERANCE_SECONDS = 5 * 60;

/**
 * rawBody: the body exactly as received, as a Buffer, before JSON.parse.
 * headers: Node's lower-cased request headers.
 * secret: the webhook_secret from the job's 202 answer.
 */
export function verifyRailCoreWebhook(rawBody, headers, secret) {
  const timestamp = headers["x-railcore-webhook-timestamp"] ?? "";
  const signature = headers["x-railcore-webhook-signature"] ?? "";
  if (!/^\d+$/.test(timestamp)) return false;
  // Refuse a send signed more than 5 minutes ago: a replay of an old callback.
  const age = Math.floor(Date.now() / 1000) - Number(timestamp);
  if (Math.abs(age) > TOLERANCE_SECONDS) return false;

  const expected = "v1=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");
  const given = Buffer.from(signature);
  const wanted = Buffer.from(expected);
  // Constant-time: never compare signatures with === or ==.
  return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
}

A receiving server built on node:http:

Node.js
import http from "node:http";

http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (chunk) => chunks.push(chunk));
  req.on("end", () => {
    const rawBody = Buffer.concat(chunks);
    const jobId = req.headers["x-railcore-webhook-id"];
    const secret = webhookSecrets.get(jobId); // saved from the 202 answer
    if (!secret || !verifyRailCoreWebhook(rawBody, req.headers, secret)) {
      res.writeHead(401).end();
      return;
    }
    const event = JSON.parse(rawBody.toString("utf8"));
    // event.status is "complete" with event.result, or "failed" with event.error.
    // A send can arrive twice (your 2xx was lost): act on each job_id once.
    res.writeHead(204).end();
  });
}).listen(8443);

Answers and retries

  • Answer with any 2xx within 5 seconds. The callback is then settled as sent.
  • After a 5xx, 408 or 429, a timeout or a dropped connection, RailCore sends it again, 3 more times, after 2, 8 and 30 seconds. Each send is signed afresh, with its own timestamp.
  • Any other answer, a 4xx or a 3xx, is final: the callback is settled as failed and not sent again.
  • A send can reach you twice when your answer is lost on the way back. Use the job id to act on each job once.

Delivery status on the job

GET /v1/jobs/{job_id} and GET /v1/jobs show how the callback went.

callback_status, Meaning table
callback_statusMeaning
not_configuredThe job was submitted without a callback_url.
pendingThe callback is not settled yet. RailCore saves the job's result before it sends the callback, so a poll can show the result while this is still pending.
sentYour endpoint answered 2xx.
failedEvery send failed, an answer was final, or the address was refused when it was resolved.

callback_attempts, present once the callback is settled, says how many sends were made: 0 to 4.

Keep the secret on your server

A webhook secret is a server credential, like the HMAC signing secret. Anyone who has it can forge callbacks for that job.

Last updated