Webhooks

A webhook is us making an HTTP request to a URL you own. When something changes in NutraSoft, we POST a small signed JSON body to that URL. You do not have to poll for it.

Webhooks or polling?

Both, in practice. They answer different questions and the honest rule is short: webhooks to react, updated_since to reconcile.

Setting one up

1. 1

   Add the endpoint

   In NutraSoft, go to Settings → Developer and choose Add webhook. The URL must be https://; we do not follow redirects. You can have up to 20 endpoints per account.

2. 2

   Copy the signing secret

   Shown when the endpoint is created. It starts with whsec_ and is what proves a request came from us. You can reveal it again later, but store it as you would any other credential.

3. 3

   Send a test event

   Use Send test on the row. It sends a ping to your real URL signed with your real secret, and shows you exactly what came back: the status code, or the connection error. Get this green before going further.

4. 4

   Tick the events you want

   A new endpoint has nothing ticked and sends nothing. Turn on only the events you will act on; you can add more at any time.

What we send

{
  "id": "evt_9f3c2a7b4d1e4f8ca1b2c3d4e5f60718",
  "type": "sales_order.status_changed",
  "created_at": "2026-09-16T14:03:11.412Z",
  "api_version": "1.0",
  "livemode": true,
  "source": { "type": "webapp" },
  "data": {
    "object_type": "sales_order",
    "id": 41207,
    "changed": ["status"],
    "snapshot": {
      "id": 41207,
      "sales_order_no": "SO-1042",
      "status": "SHIPPED",
      "updated_at": "2026-09-16T14:03:11.402Z"
    }
  }
}

Verifying the signature

Anyone can POST to your URL. The signature is what tells you a request is really from us. Compute HMAC-SHA256 over {timestamp}.{raw body} with your signing secret, and compare in constant time. Reject anything older than 5 minutes.

const crypto = require("crypto");

// Express: keep the raw bytes. express.json() alone discards them.
app.post("/hooks/nutrasoft",
  express.raw({ type: "application/json" }),
  (req, res) => {
    if (!verify(req.body, req.get("NutraSoft-Signature"), process.env.WHSEC)) {
      return res.sendStatus(400);
    }
    const event = JSON.parse(req.body.toString("utf8"));

    // Answer first. Do the slow work afterwards, or we will time out
    // and send the whole thing again.
    res.sendStatus(200);
    enqueue(event);
  });

function verify(rawBody, header, secret) {
  if (!header) return false;
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=", 2))
  );
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(parts.t + "." + rawBody)
    .digest("hex");

  // Every v1= in the header: during a secret rotation there are two.
  return header
    .split(",")
    .filter((p) => p.startsWith("v1="))
    .some((p) =>
      crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.slice(3)))
    );
}

import hashlib, hmac, time

TOLERANCE = 300

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    if not header:
        return False
    fields = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    try:
        timestamp = int(fields["t"])
    except (KeyError, ValueError):
        return False
    if abs(int(time.time()) - timestamp) > TOLERANCE:
        return False

    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()

    # Any v1= matches: two are sent while a secret is being rotated.
    return any(
        hmac.compare_digest(expected, value)
        for key, value in (p.split("=", 1) for p in header.split(",") if "=" in p)
        if key == "v1"
    )

<?php
function nutrasoft_verify(string $rawBody, ?string $header, string $secret): bool {
    if (!$header) return false;
    $fields = [];
    foreach (explode(',', $header) as $part) {
        [$k, $v] = array_pad(explode('=', $part, 2), 2, null);
        $fields[$k][] = $v;
    }
    $t = (int)($fields['t'][0] ?? 0);
    if ($t === 0 || abs(time() - $t) > 300) return false;

    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    foreach ($fields['v1'] ?? [] as $candidate) {
        if (hash_equals($expected, (string)$candidate)) return true;
    }
    return false;
}

Not hearing your own writes

Every event carries source, saying what caused the change: webapp (a person in NutraSoft), system (a scheduled job or one of our integrations), or api naming the key that made the call by its key_prefix and key_last4.

1. In your code: compare source.key_prefix with the start of the key you hold and return 200 without acting. Both values come straight off the key in your own configuration, so there is nothing extra to fetch or store, and rotating the key keeps working.
2. In NutraSoft, with no code at all: on the endpoint, set *Changes made through the API* to skip your keys. Changes made by people in the ERP, by the scheduler and by our own integrations still arrive.

// Skip the echo of our own writes. Both halves are derived from the
// key already in our configuration, so a rotated key needs no change here.
const ours = {
  prefix: NUTRASOFT_API_KEY.slice(0, 12),
  last4: NUTRASOFT_API_KEY.slice(-4),
};

if (
  event.source.type === "api" &&
  event.source.key_prefix === ours.prefix &&
  event.source.key_last4 === ours.last4
) {
  return res.sendStatus(200);
}

One more thing works in your favour: a write that changes nothing produces no event at all. Writing back the same value you were just told is silent.

Retries

A delivery succeeds on any 2xx within 15 seconds. Anything else (a 500, a 404, a timeout, a bad certificate) is a failure, and we try again on this schedule:

That is 4 attempts over about 15 hours. After the last one the delivery is marked Gave up, and stays visible in your delivery history so you can see exactly what you missed and fetch it with a GET.

You never have to wait out a gap. The five hours is for the case where nobody is watching. If you have just deployed a fix, open Deliveries on the endpoint and press Send again. It goes out on the next tick, it works on a delivery that is still waiting for its next automatic attempt as well as on one that gave up, and you can press it as many times as you need. Pressing it twice queues one delivery, not two.

• 429: we honour your Retry-After.
• 410 Gone: we take it as a deliberate unsubscribe and switch the endpoint off immediately. Useful when a receiver is decommissioned.
• A redirect: treated as a failure. We never follow one.
• If an endpoint fails everything for a day, we switch it off and email your account's developer contacts. Nothing is deleted; one click re-enables it.

What we guarantee, and what we do not

Rotating the secret

Rotate secret issues a new one. For the next 24 hours we sign every delivery with both, sending two v1= values in the header, so you can deploy the new secret without an outage, which is why the snippets above check every v1= rather than just the first. Choose the immediate option instead if you believe the old secret has leaked.

Test mode

Your test account is a separate account, so it has its own webhook endpoints and its own secrets. Events from it carry livemode: false. Writes you make with a nsk_test_ key produce real events there, so you can drive a full end-to-end test from your own code before touching live data.

Troubleshooting

Your delivery history is kept for 30 days under Deliveries on each endpoint, with what we sent, what came back and a Send again button. When you contact support, quote the NutraSoft-Delivery-Id.

A delivery we gave up on is kept longer, for 90 days, so a failure is still there to look at weeks after it happened. After 30 days we drop the payload and your server's reply from it, keep the rest, and Send again stops working on it: there is nothing left to send by then. Replay a failure before that, or re-read the affected records with updated_since.