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.
On this page

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,beforeSubmitandafterSubmiton a record type.afterSubmitruns after the record is saved, which makes it the right hook for "a sales order was created or edited, tell another system." - The
N/httpsmodule 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 asHostandContent-Length, are set by NetSuite and dropped if you pass them. - The
N/httpmodule 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/httpsthe 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.postfails, 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.xor 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.postreturns 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.
Related
- Webhooks to internal servers: how the relay agent works.
- ServiceNow webhooks and Salesforce Outbound Messages: the same pattern for other enterprise systems.
- Azure Relay alternative: Hybrid Connections compared for on-prem delivery.
- Webhook retries and idempotency: make the receiver safe against duplicates.
- Buying for a company? The enterprise page covers SOC 2 Type II, SSO, security reviews and annual billing by invoice and purchase order.
