Webhooks
Prodaksha tells your system what happened at the factory by sending a signed POST to an address you register.
Register an address
curl -s -X POST $BASE/webhooks \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"url": "https://your-system.example/prodaksha/events", "events": ["*"]}'
eventslists the events you want, or["*"]for all of them.- The answer carries the endpoint's
secretonce. Store it safely. GET /webhookslists your endpoints;DELETE /webhooks/{id}stops one. To change the secret, register a new endpoint and delete the old one.- An endpoint receives only events that happen after it was registered; it never gets old history.
What arrives
POST /prodaksha/events HTTP/1.1
Content-Type: application/json
X-Event-Id: 01JD3K9W8T5Q…
X-Timestamp: 1763193300
X-Signature: sha256=5f2c0a…
{
"id": "01JD3K9W8T5Q…",
"type": "consignment.received",
"occurred_at": "2026-11-15T11:15:00+03:00",
"company_id": 12,
"data": {"reference_no": "VAB-26-7", "intake_ticket_no": "IN-26-0311", "received_qty": 1240, "unit": "kg", "moisture": 11.2, "reject_qty": 6, "variance_qty": -10.5, "variance_status": "within", "received_at": "2026-11-15T11:14:00+03:00"}
}
company_id is the factory's id on Prodaksha. data.reference_no is your delivery's number, so you can find your own record.
Check every event
- Compute
sha256=+ the HMAC-SHA256 of the raw body (the exact bytes, before parsing) with your secret. Compare it withX-Signaturein constant time. - Refuse a
X-Timestampmore than 5 minutes from your clock. Keep your server's clock right (NTP). - Keep the
X-Event-Idof events you processed and ignore repeats: a retry can deliver the same event twice. - Reply
2xxwithin 10 seconds. Do slow work afterwards (a queue), not before replying. - An event about a
reference_noyou do not know: reply2xxand ignore it.
// PHP
$raw = file_get_contents('php://input');
$ok = hash_equals('sha256=' . hash_hmac('sha256', $raw, $secret), $_SERVER['HTTP_X_SIGNATURE'] ?? '')
&& abs(time() - (int) ($_SERVER['HTTP_X_TIMESTAMP'] ?? 0)) <= 300;
# Python
import hmac, hashlib, time
ok = hmac.compare_digest("sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest(), headers["X-Signature"]) \
and abs(time.time() - int(headers["X-Timestamp"])) <= 300
// Node.js (use the raw body, e.g. express.raw({type: "application/json"}))
const expected = Buffer.from("sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex"));
const given = Buffer.from(req.headers["x-signature"] || "");
const ok = given.length === expected.length && crypto.timingSafeEqual(expected, given)
&& Math.abs(Date.now() / 1000 - Number(req.headers["x-timestamp"])) <= 300;
Retries
If your address does not answer 2xx in time, the event is sent again after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then set aside. The factory and the platform administrator can see deliveries that are waiting or failed. If you were down for longer than that, read what you missed through the API (GET /consignments/{id}, /intakes, /statements, /invoices, /payments).
Events about one delivery can arrive out of order after a retry. Use occurred_at and the record's own state, not the order of arrival.
Events for supplier and society systems
These carry data.reference_no, your delivery number.
| Event | Sent when | data |
|---|---|---|
consignment.received |
The delivery was weighed in | reference_no, intake_ticket_no, received_qty, unit, moisture, reject_qty, variance_qty, variance_status, received_at, scale_id |
consignment.variance_decided |
A weight difference was approved or disputed | reference_no, decision (approved, disputed, accepted), note, via (ui, api, fpobox) |
run.completed |
A run that used your goods finished | reference_no, work_order_ref, outputs: [{item, grade, qty, unit, bags, bag_unit, packets, lot_no, role}], yield_pct, completed_at, outturn_no, quality: [{check, name, stage, outcome, checked_at, results: [{parameter, name, value, unit, passed}]}] |
lot.hold_changed |
A lot made from your goods was put on hold or released after a quality check | reference_no, lot_no, status, reason |
statement.issued |
Toll work: the factory's charges | reference_no, statement_no, lines: [{description, qty, unit, rate, amount, kind}] (kind: tariff or charge), total, currency, due_date |
toll.dispatched |
Toll work: your products sent back to you | reference_no, dispatch_no, client_ref, dispatched_at, vehicle, permit_no, lines: [{item, grade, lot_no, qty, unit}] |
sale.proceeds |
Toll work: your products sold on your behalf | reference_no, proceeds_no, client_ref, channel (broker, direct), sale_no, sold_at, buyer_name, lines: [{item, grade, qty, unit, price, amount, lot_no, buyer}], gross, charges: [{description, amount}], net, currency |
invoice.issued |
Purchase: the factory's self-billed invoice for what it bought from you | reference_no, invoice_no, lines, total, currency, einvoice_control_no |
payment.recorded |
The factory paid you | reference_no, invoice_no, amount, rail, txn_ref, paid_at; for proceeds, kind: "proceeds" and invoice_no = the proceeds number |
One event is sent per delivery: if a run used goods from three of your deliveries, you get three run.completed, each with its own reference_no.
Events about the factory
| Event | Sent when | data |
|---|---|---|
company.activated |
The factory starts operating on Prodaksha (subscription active or trial) | company_id, name, country, status, banned, at |
company.suspended |
The factory stops operating | the same |
Other events
For accounting, buyer and dashboard integrations: consignment.declared, intake.posted, run.reversed, job_card.finished, stock.document.posted, stock.document.reversed, journal.posted, sales_order.confirmed, delivery.posted, delivery.returned, sales_invoice.posted, credit_note.posted, einvoice.signed, receipt.recorded, receipt.matched, approval.requested, approval.decided. The API reference always has the current list.
