Skip to main content
When a package moves through its signing flow, you usually want two things: your own system to be told when something changes, and the end user to be sent somewhere sensible after they act. NSEV gives you several mechanisms for this, set when you create the package or when you create an actor. This page explains what each one is, when it fires, and how to use it. The mechanisms fall into two groups:
  • Callbacks - server-to-server HTTP POSTs from NSEV to your system (CallBackUrl, NotificationCallBackUrl).
  • Redirects - where the end user’s browser is sent after they finish (RedirectUrl, DefaultRedirectUrl, F2fRedirectUrl, controlled by RedirectType).
Plus SuppressNotifications, which turns off the emails NSEV would otherwise send to an actor.

​
CallBackUrl - status-change callbacks

CallBackUrl is a package-level property. When you set it on the package, NSEV sends an HTTP POST to that URL whenever the package’s status changes, so an external system can react. When it fires. A callback is sent on end-user actions, including:
  • a user changes the package from Draft to Pending, or revokes it, in the Document Portal
  • a user clicks confirm in a drag-and-drop editor window
  • a signer completes all their signing fields
  • all signers have signed the package
  • a signer rejects the package
  • an approver approves the package
  • form fillers complete their fields
  • the system sets the package to Failed
API requests never trigger a callback. Callbacks fire only when an end user triggers an action in the NSEV WebPortal or Signer application. More triggers may be added in future versions.
The payload. The POST body is application/json containing packageId and packageStatus:
If your system needs more than the status, call GET /packages/{packageId} to fetch the full package. How to use it well.
  • The CallBackUrl must be a valid, absolute URL with no query parameters.
  • The callback has a 100-second timeout. If your service does not respond in time, NSEV forces the timeout and finishes the flow as if it had received 200 OK. Respond as quickly as possible and run any follow-up work asynchronously, so your processing never blocks the signing flow.
  • On error, NSEV retries the callback 3 times over 3 retry cycles by default. Administrators can customize the retry mechanism.
NSEV uses one-time signing URLs: once an action link is clicked it expires, and a new link must be requested. NotificationCallBackUrl is a package-level property that, when set, calls your remote service each time a signer requests a new link - instead of NSEV sending its usual email. Your service then decides what to do (for example, deliver the new link through your own channel). When it fires. Unlike CallBackUrl, which fires on major state changes, the notification callback can fire repeatedly without an apparent status change - so the payload tells you which kind of notification was requested. The remote service is called once per user action, with no retry unless the end user requests another notification. The payload. An application/json POST body containing: Current notificationTypeKey values:
This list may grow. Your service must ignore notificationTypeKey values it does not recognize without returning an error response.
NSEV waits for your service to finish before returning control to the end user, so it must respond within seconds. On error, NSEV retries 3 times over 3 retry cycles by default.
NotificationCallBackUrl is separate from SuppressNotifications. The emails NSEV sends when a package is created, revoked, and so on are governed by SuppressNotifications, not by the notification callback.
SuppressNotifications is an actor-level property (default false). When set to true on an actor, NSEV does not send that actor the emails it would normally send about the package. This is the basis of the technical-user pattern: rather than letting NSEV email your signers directly, you suppress its notifications and deliver the signing links yourself - through your own application, email, or portal. Pair it with NotificationCallBackUrl so that when a one-time link expires and the user requests a new one, your system is called to deliver the replacement instead of NSEV sending an email.
Automatic reminders and expiration reminders are not affected by SuppressNotifications: an actor with SuppressNotifications set to true still receives automatic reminders and the expiration reminder if those are configured on the package.

​
RedirectUrl - where a user goes after acting

RedirectUrl is an actor-level property. When a Signer or FormFiller finishes their action, their browser is redirected to this URL. If no RedirectUrl is set, the end user has to close the browser tab themselves. NSEV appends query parameters to the URL so your return endpoint knows what happened:
  • SessionID - the package signing session (the actor’s ActorId)
  • ExternalReference - the stakeholder’s ExternalReference
  • Status - FINISHED, REJECTED, or INVALIDTOKEN
  • PackageExternalReference - the package’s ExternalReference
For this to be useful, set meaningful ExternalReference values on your packages and stakeholders; see The package model → ExternalReference.
The redirect happens client-side, so the end user can counterfeit the returned Status. Never trust the redirect alone to confirm signing. Verify the outcome through a second secure channel - the CallBackUrl - or by checking session state, and then confirm with a GET /packages/{packageId}/status call.
RedirectUrl must be a valid, absolute URL with no existing query parameters.

​
DefaultRedirectUrl - a package-wide fallback

DefaultRedirectUrl is a package-level property. It sets the URL stakeholders are redirected to after completing their actions when an actor has no RedirectUrl of its own. It is applied on package submit. Use it to set one fallback redirect for the whole package instead of repeating the same RedirectUrl on every actor.

​
RedirectType - when the redirect fires

RedirectType is an actor-level property that controls when the redirect happens. It applies only to Signer and FormFiller actors, and is only valid together with a RedirectUrl - the API rejects a RedirectType set without one. The possible values are:
RedirectType is exposed only on Signer and FormFiller actors in the API - not on Approver or Receiver actors.

​
F2fRedirectUrl - face-to-face signing only

F2fRedirectUrl is a package-level property for face-to-face signing in the Document Portal only. The end user is redirected to it after all fields have been signed or rejected face to face. Do not confuse it with the regular RedirectUrl - F2fRedirectUrl applies only to face-to-face signing, not to remote signing sessions. NSEV appends these query parameters:
  • SessionID - the package signing session (the package’s ID)
  • Status - FINISHED, REJECTED, or INVALIDTOKEN
  • PackageExternalReference - the package’s ExternalReference
As with RedirectUrl, the F2F redirect happens client-side and can be counterfeited. Confirm the outcome through the CallBackUrl or session state, then verify with a GET /packages/{packageId}/status call.
F2fRedirectUrl must be a valid, absolute URL with no existing query parameters. Close-button interaction. During asynchronous signing, a signer can normally use a Close button to leave while signing continues in the background. When an F2fRedirectUrl is configured, that Close button is unavailable; instead the signer sees a message telling them they will be redirected once signing finishes.

​
Polling versus callbacks

There are two ways to find out when a package has progressed:
  • Callbacks (recommended for integrations). Set a CallBackUrl and let NSEV notify your system on each status change. This avoids repeated polling, reacts immediately, and scales better. Make sure your callback endpoint responds fast and does its real work asynchronously (remember the 100-second timeout).
  • Polling (fine for simple flows). Call GET /packages/{packageId}/status periodically until the package reaches a terminal status such as Finished. This is simpler to build and is a reasonable choice for low-volume or one-off flows where you do not want to expose a public callback endpoint.
The Send a document for signing tutorial uses polling for simplicity; switching that final step to a CallBackUrl is the recommended approach for a production integration.