Understand the difference between request idempotency, resource IDs, and webhook deduplication in NextSign.

Idempotency

Idempotency means a repeated operation should not create unintended duplicates or side effects. This matters when your client retries requests or when webhook deliveries are repeated.

Request Idempotency

NextSign does not currently provide built-in request idempotency for create endpoints such as Case Create or Forms Submit.

That means sending the same POST request twice can create two separate resources if both requests are accepted.

Do not treat _id or referenceId as a built-in idempotency key for requests. They do not prevent duplicate creates by themselves.

What `_id` Means

_id is the unique identifier of a resource after it exists.

Use _id for:

fetching an existing case, flow, or form
storing relations between your records and NextSign resources
correlating webhook payloads with resources already stored in your system

_id is resource identity, not request idempotency. You only know it after the resource has been created.

What `referenceId` Means

Case creation and form submission also support referenceId. Use it as a business correlation field between your system and NextSign.

Typical uses:

attach your internal order or contract number to a case
trace retries and support cases more easily
reconcile user actions and webhook events in your own system

referenceId is useful for your own matching and reconciliation, but it is not a uniqueness guarantee enforced by the API.

Recommended Pattern for Create Requests

For create flows where the client might retry:

Generate your own operation ID before sending the request
Store the request intent in your own database
Send the request once
If the result is unknown, reconcile using your own stored context before retrying
Store the returned _id once the request succeeds

Webhook Deduplication

Webhook deliveries can be repeated when delivery fails and is retried. Your webhook consumer should therefore be idempotent even though the create endpoints themselves are not request-idempotent.

Because the same case can emit multiple webhook events over time, a practical event-level deduplication key is:

function getIdempotencyKey(payload) {
  const entity = payload.case || payload.flow;
  return [payload.trigger, entity?._id, entity?.updatedAt].filter(Boolean).join(':');
}

Store that key in your database or queue processor and ignore deliveries you have already handled successfully.

Good Defaults

make write operations originate from your backend, not directly from the browser
log your own operation ID together with referenceId and the returned _id
do not retry unknown POST outcomes blindly
make webhook handlers safe to run more than once