Configuring a Webhook Endpoint

Create a public HTTPS endpoint and register it in the HellOOpass dashboard.

Placeholder webhook contract

Event names, signature headers, and payload fields are illustrative until the finalized webhook specification is published.

HellOOpass delivers events to a public HTTPS URL you register once in the merchant dashboard.

Requirements

Public HTTPS URL with a valid TLS certificate — HTTP is not accepted in production
Fast 2xx responses: acknowledge first, then do heavy work asynchronously
Stable, versionable URL such as https://your-app.com/webhooks/helloopass
Signing secret kept in an environment variable (WEBHOOK_SECRET), never in source control
Handler designed for duplicate deliveries

Configure

Open webhook settings

Go to Project Settings → Webhooks in the HellOOpass merchant dashboard.

Add your endpoint URL

Paste your HTTPS URL and pick the events to receive (Webhook Event Types).

Copy the signing secret

Store it as WEBHOOK_SECRET and plan for rotation.

Handler pattern

Verify X-HellOOpass-Signature against the raw request body.
Persist the event by id (insert-or-ignore) to durable storage.
Enqueue fulfillment work on a background queue.
Respond 200 OK as soon as persistence succeeds.

app.post("/webhooks/helloopass", express.raw({ type: "application/json" }), async (req, res) => {
  const raw = req.body.toString();
  const sig = req.headers["x-helloopass-signature"];
  if (!verifySignature(raw, sig, process.env.WEBHOOK_SECRET)) return res.status(401).send("invalid");
  const event = JSON.parse(raw);
  await db.insertEvent(event.id, event); // insert-or-ignore by event id
  await queue.enqueue("helloopass-event", event);
  res.status(200).send("ok");
});

Tunnel your local server during development, then confirm end-to-end behavior with Testing Webhooks.