Blog

NetSuite Webhooks: Send Record Events to an On-Prem Endpoint

NetSuite has no webhooks screen. Here is how to send record events with a SuiteScript User Event script and N/https, the timeout and HTTPS limits to plan for, and how to reach a server behind your firewall.

6 min read
Karolis Rusenas
On this page

NetSuite webhooks to an on-prem endpoint

NetSuite doesn't have a webhooks screen. To push record events out, deploy a SuiteScript User Event script that calls https.post in afterSubmit. If the receiver is on your private network (an on-prem warehouse system, an EDI gateway, an internal pricing API), point the script at a public Webhook Relay URL and run the relay agent next to that system. The agent connects out, so you open no inbound ports, and every event is stored and retried if the internal side is down.

How NetSuite sends webhooks

Look for "webhooks" in NetSuite and you'll find integrations, connectors and partner tools, but no native setting that posts a record to a URL when it changes. Here's what actually exists.

  • SuiteScript User Event scripts. A User Event script runs beforeLoad, beforeSubmit and afterSubmit on a record type. afterSubmit runs after the record is saved, which makes it the right hook for "a sales order was created or edited, tell another system."
  • The N/https module sends the request. Oracle's documentation says it "does not allow the HTTP protocol": HTTPS only, TLS 1.2, and a full certificate chain. Some headers, such as Host and Content-Length, are set by NetSuite and dropped if you pass them.
  • The N/http module accepts plain HTTP or HTTPS URLs. It's useful for test endpoints, not for anything carrying business data over the internet.
  • Workflows (SuiteFlow). None of the built-in workflow actions sends an HTTP request. If an admin wants to trigger a call from a workflow, they use the Custom action, which runs a Workflow Action Script, and that script calls N/https the same way.
  • Scheduled and Map/Reduce scripts suit batches, such as "send every invoice changed in the last hour," when you don't need each event in real time.

Limits to plan for

  • Timeouts. Oracle documents 5 seconds to connect and 45 seconds to send the request payload. After that the call fails with SSS_REQUEST_TIME_EXCEEDED.
  • The save waits for you. A User Event script runs inside the user's save. A slow receiver makes every sales order save slow, and a receiver that's down produces errors unless you catch them.
  • Governance. Each HTTP call uses governance units from the script's budget, so one call per record is fine but loops over many records belong in Map/Reduce.
  • No retries. If https.post fails, nothing resends it. You'd have to write failed events to a custom record and resend them from a scheduled script.
  • Cloud egress only. The script runs in Oracle's data centres. It can't reach 10.x, 192.168.x or a hostname that only resolves on your network.

That last point is why on-prem ERP integrations so often end up with a hand-built middleware box in a DMZ.

Send NetSuite events to an internal server with Webhook Relay

1. Start the agent next to the on-prem system

On a host that can reach the receiving service, install the relay CLI, log in, and run:

relay forward --bucket netsuite-orders http://wms.internal:9000/netsuite/sales-orders

The command creates the bucket, prints its public HTTPS input URL (https://my.webhookrelay.com/v1/webhooks/<input-id>), and starts the agent. The agent only connects out and can go through a corporate HTTP proxy. The internal endpoint can be plain HTTP or use your internal CA, even though NetSuite itself insists on public HTTPS. For production, run it as a Docker container, a system service, or in Kubernetes with the operator.

Turn on token authentication in the bucket settings (how) so the input only accepts requests that carry your bearer token.

2. Deploy the User Event script

/**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 */
define(['N/https', 'N/runtime', 'N/log'], (https, runtime, log) => {
  const afterSubmit = (context) => {
    const { CREATE, EDIT } = context.UserEventType;
    if (context.type !== CREATE && context.type !== EDIT) return;

    const rec = context.newRecord;
    const script = runtime.getCurrentScript();
    const url = script.getParameter({ name: 'custscript_whr_url' });
    const token = script.getParameter({ name: 'custscript_whr_token' });

    try {
      const res = https.post({
        url,
        headers: {
          'Content-Type': 'application/json',
          Authorization: 'Bearer ' + token
        },
        body: JSON.stringify({
          event: context.type,          // create / edit
          recordType: rec.type,
          id: rec.id,
          tranid: rec.getValue({ fieldId: 'tranid' }),
          entity: rec.getValue({ fieldId: 'entity' }),
          total: rec.getValue({ fieldId: 'total' }),
          status: rec.getValue({ fieldId: 'status' })
        })
      });
      log.audit({ title: 'Webhook sent', details: res.code });
    } catch (e) {
      log.error({ title: 'Webhook failed', details: e.message });
    }
  };

  return { afterSubmit };
});

Upload the file, create a Script record, add the two parameters (the input URL and the token), and deploy it on the record type, for example Sales Order. Keeping the URL and token in parameters means you can point sandbox and production at different buckets without editing code.

3. The internal system receives a normal POST

The agent delivers the request with its JSON body and headers to http://wms.internal:9000/netsuite/sales-orders. The bucket's request log records each delivery and the response your system returned, which helps when finance asks whether order SO-10432 was ever sent.

Why this helps the save path

Webhook Relay accepts the request and answers within milliseconds, then delivers to your network asynchronously. So:

  • Users don't wait on your internal system. The https.post returns fast whether the warehouse system is busy, slow or offline, and you stay well inside the 45-second limit.
  • Outages don't lose orders. If the internal system or the agent is down, requests are stored. They can be replayed when the agent reconnects, and durable retries keep retrying failed deliveries with backoff for up to 30 days. You don't need a custom record and resend script.
  • Payload changes stay out of SuiteScript. If the receiver wants a different shape, field names, or an extra auth header, a transform function on the output handles it. Redeploying SuiteScript for a field rename isn't fun.
  • One event, several systems. Add outputs, or run agents in other sites against the same bucket, to feed the warehouse, the data warehouse and an audit log from one script.

Test first: point the script parameter at a free Webhook Bin in your sandbox account to see exactly what NetSuite sends before the internal endpoint exists.

Frequently asked questions

Does NetSuite support webhooks?

Not as a configurable feature. There is no screen where you register a URL against record events, and none of the built-in SuiteFlow workflow actions sends an HTTP request. The standard approach is SuiteScript: a User Event script whose afterSubmit function posts the record to your endpoint with the N/https module. Workflows can do the same through a custom action that runs a Workflow Action Script.

How do I send a webhook from NetSuite when a record is saved?

Deploy a SuiteScript 2.x User Event script on the record type, for example Sales Order. In afterSubmit, read the fields you need from context.newRecord, build a JSON body and call https.post with your endpoint URL and headers. Wrap it in try/catch so a failed call is logged instead of surfacing as an error to the user.

Can NetSuite post to an HTTP (not HTTPS) URL or an internal IP address?

N/https only accepts HTTPS URLs with TLS 1.2 and a full certificate chain. The separate N/http module accepts plain HTTP URLs. Neither can reach a private address on your network, because the script runs in NetSuite's cloud. Send to a public Webhook Relay URL instead and let the relay agent inside your network deliver to the internal service over HTTP or HTTPS.

What is the NetSuite https.post timeout?

Oracle's documentation gives 5 seconds to connect and 45 seconds to send the request payload; past that the call fails with SSS_REQUEST_TIME_EXCEEDED. Because a User Event script runs while the record is being saved, a slow endpoint also slows down the save for the user. An endpoint that acknowledges immediately and delivers asynchronously avoids both problems.

How do I keep NetSuite events if the on-prem system is down?

A plain https.post doesn't retry; if the call fails, your script has to queue and resend it. With Webhook Relay the request is accepted and stored at once, then delivered to the internal system when it is reachable, with durable retries for up to 30 days and replay from the request log.