Core concepts
Signed callbacks when an async job ends.
What a webhook is for
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.Add callback_url to the body of POST /v1/jobs/route-scan or POST /v1/jobs/hopping.
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.
{
"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_..."
}
}https URL on a public host, on port 443 or a port from 1024 up.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.One POST with a JSON body when the job ends.
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":{ ... }}{ "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 every callback before you trust it. Sign the raw bytes you received: parsing the JSON and serializing it again changes them.
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:
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);GET /v1/jobs/{job_id} and GET /v1/jobs show how the callback went.
| callback_status | Meaning |
|---|---|
not_configured | The job was submitted without a callback_url. |
pending | The 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. |
sent | Your endpoint answered 2xx. |
failed | Every 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
Last updated