Webhooks (Server-to-Server)

Omniware posts JSON over HTTPS to a URL you register against your merchant account whenever certain events occur. Webhooks (Omniware calls these S2S callbacks) complement the status APIs and help you receive final payment, settlement, payout, and credit-notification events server-to-server.

What you'll receive

Event	When it fires	Endpoint reference
Payment	Customer completes (or fails) a checkout.	Payments → S2S
Settlement	Funds are released to your bank account.	Payments → S2S
Payout	A fund transfer reaches a terminal state.	Payouts → S2S
Credit notification	An e-collect virtual account receives money.	Credit notification

Configuring your endpoint

Register the URL in the Omniware dashboard against your merchant account. One URL per event family. The URL must:

• Be HTTPS.
• Accept POST with Content-Type: application/json.
• Respond with 2xx only after the payload is validated and recorded.

Verifying the payload

Every webhook body includes a hash field. Recompute it with your salt and the rest of the body before trusting the payload — anyone can POST arbitrary JSON to a public URL.

import crypto from "node:crypto";

app.post("/webhooks/omniware/payments", (req, res) => {
  const sent = req.body.hash;
  const { hash, ...rest } = req.body;
  const computed = crypto
    .createHash("sha512")
    .update(process.env.OMNIWARE_SALT + JSON.stringify(rest))
    .digest("hex")
    .toUpperCase();

  if (!sent || sent !== computed) {
    return res.status(400).send("bad hash");
  }

  // safe to process
  res.sendStatus(200);
});

See Hash calculation → Verifying a response hash for the algorithm in other languages.

Idempotency

Design webhook handlers to be idempotent. Use your own reference (order_id, merchant_reference_number, or transaction_id) as the processing key and ignore a repeated event that you've already recorded.

Acknowledgement and replay

The PDFs document the callback payloads but do not define retry timing for failed webhook delivery. Treat non-2xx responses as unacknowledged, reconcile from the matching status API, and confirm replay behaviour with Omniware support before depending on automatic retries.

tip

Treat the webhook as authoritative after hash verification. If you're showing the customer a confirmation page immediately on return_url, still confirm with the webhook (or Payment Status) before fulfilling.