Webhooks

Sign webhooks are long-lived subscriptions. You register an endpoint once per API application in the Nitro Admin Portal, and Nitro delivers envelope, document and signature events to it as they happen.

Looking for per-request notifications on asynchronous PDF Services jobs instead? See Callbacks. The two mechanisms are configured differently and are not interchangeable.

Overview

Nitro allows applications added to the API service to register a webhook URL to receive notifications of real-time events in the platform.

How to register a webhook

Webhooks are managed per API Application in the Nitro Admin Portal. One webhook is permitted per application, though the same endpoint URL can be reused across multiple applications. To register a webhook:

Open your application

In the Admin Portal, go to your API Application’s details and select Add Webhook.

Enter your endpoint URL

Enter your webhook URL. You can select Test Webhook at this point to confirm your endpoint is reachable before continuing.

Choose your events

Select Continue, then choose which event types you want to subscribe to. Create is enabled once at least one event is selected.

Save your client secret

On creation, Nitro generates a client secret for your webhook.

Store your Client Secret in a secure location. Do not save it on personal devices, mobile phones, shared folders, or source code repositories. Instead, use a secrets manager to store it and expose it to your application using that manager’s best practices.

Your client secret is used to verify incoming event signatures. See Security and Verification.

Editing a webhook

From your application’s details, select Edit Webhook. The URL and event fields become editable, and Test and Delete are disabled while you’re editing. Select Save Changes once your URL is valid and at least one event is selected, or cancel to revert without saving.

Deleting a webhook

Select Delete Webhook, then confirm in the dialog. This immediately stops all event delivery to that endpoint. You’ll need to add a new webhook to resume receiving events.

Deleting a webhook does not affect past deliveries or in-flight retries already queued at the time of deletion.

After Registration

Once your webhook is registered, we recommend the following best practices:

Scope down events Only subscribe to events that your application needs to handle. This helps reduce unnecessary load on both your server and the Nitro system.
Test your webhook Select Test Webhook from your application’s details at any time to confirm your endpoint is responsive.
- A successful test returns: “Test event delivered successfully. Your endpoint is responsive.”
- A failed test (4xx, 5xx, or timeout) returns: “Test event could not be delivered.”

Handling Events

Event Payload

When events occur on your application, Nitro will send a POST request to your webhook URL with a JSON payload containing event details and data. The JSON payload will have the following structure:

{
  "id": "<string>",
  "type": "<string>",
  "created": "<string>",
  "data": {...}
}

id: The event’s unique id.
type: Enum of the event’s type. Possible values: EnvelopeCreated, EnvelopeDocumentAdded, EnvelopeDocumentDeleted, EnvelopeSentForSignature, EnvelopeCancelled, SignatureRequestReassigned, SignatureRequestDeclined, SignatureRequestSigned, EnvelopeSigningCompleted, EnvelopeSealed, OwnerMessaged.
created: UTC timestamp of the creation of the event.
data: An object with the minimum relevant data for the event. If your process requires additional data, you have to request it via the API.

Event Types

The JSON payload of the event will have the following object structure, with the data field varying depending on the event type.

EnvelopeCreated

The envelope has been created.

    {
        "id": "<event_id>",
        "type": "EnvelopeCreated",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            }
        }
    }

EnvelopeDocumentAdded

A document has been uploaded and attached to the envelope.

    {
        "id": "<event_id>",
        "type": "EnvelopeDocumentAdded",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            }
            "document": {
                "id": "<document_id>",
                "name": "<file_name>",
                "fileSizeBytes": 123456,
                "pages": 12,
                "origin": "Upload"
            }
        }
    }

EnvelopeDocumentDeleted

A document has been deleted from an envelope.

    {
        "id": "<event_id>",
        "type": "EnvelopeDocumentDeleted",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            },
            "document": {
                "id": "<document_id>"
            }
        }
    }

EnvelopeSentForSignature

An envelope has been sent for signature.

    {
        "id": "<event_id>",
        "type": "EnvelopeSentForSignature",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            },
            "documents": [
                { "id": "<document_id>", "name": "<file_name>", "fileSizeBytes": 123456, "pages": 12, "origin": "Upload" }
            ],
            "participants": [
                { "email": "<participant_email>", "role": "<participant_role>" },
                { "email": "<participant_email>", "role": "<participant_role>" }
            ]
        }
    }

EnvelopeCancelled

The envelope has been cancelled by the owner.

    {
        "id": "<event_id>",
        "type": "EnvelopeCancelled",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            }
        }
    }

SignatureRequestReassigned

A signature request has been forwarded to another participant.

    {
        "id": "<event_id>",
        "type": "SignatureRequestReassigned",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            },
            "signature": {}
        }
    }

SignatureRequestDeclined

A signature request has been declined.

    {
        "id": "<event_id>",
        "type": "SignatureRequestDeclined",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            },
            "signature": {
                "declinedBy": "<participant_email>"
            }
        }
    }

SignatureRequestSigned

A participant has signed the envelope.

    {
        "id": "<event_id>",
        "type": "SignatureRequestSigned",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            },
            "signature": {
                "signedBy": "<participant_email>",
                "order": 1
            }
        }
    }

EnvelopeSigningCompleted

All participants have signed and sealing will start.

    {
        "id": "<event_id>",
        "type": "EnvelopeSigningCompleted",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            }
        }
    }

EnvelopeSealed

The envelope is sealed and digitally signed. No further changes can be made.

    {
        "id": "<event_id>",
        "type": "EnvelopeSealed",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            }
        }
    }

OwnerMessaged

The owner received a message from one of the signers.

    {
        "id": "<event_id>",
        "type": "OwnerMessaged",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            },
            "signer": {
              "email": "<participant_email>",
              "order": 1
            },
            "message": "<message sent by signer>"
        }
    }

Webhook’s Response

When delivering events, our system interprets your webhook’s response code as follows:

2xx responses: Any response in the 200–299 range is treated as a success. No further delivery attempts are made.
4xx responses: Any response in the 400–499 range indicates the request reached your server. These are treated as acknowledged, and no further delivery attempts are made.
5xx responses or network errors: Responses in the 500–599 range, or network failures, are considered temporary errors. Nitro will retry event delivery.

Backwards Compatibility

Events are implemented with backward compatibility, similar to the Nitro API. This means there is no versioning for Events. Once your event handlers are implemented, you can expect them to continue working reliably. Any data added to support new features will be included as optional fields, which can be ignored if your application does not require them.

Event Ordering

The delivery order of events is not guaranteed to match the real-world order of occurrence. In most cases, events will arrive in the same sequence as the actions that triggered them. However, network conditions, retries, and asynchronous processes may result in out-of-order delivery. For example, when the last participant signs an envelope, you might receive events in this order:

EnvelopeSigningComplete
SignatureRequestSigned

In this case, the SignatureRequestSigned event represents the last signer completing their signature, which logically happens before the EnvelopeSigningComplete event. Because these actions occur almost simultaneously, the events are sometimes delivered in the reverse order. We recommend that your application does not rely on strict event ordering:

Use unique event IDs to de-duplicate and track processing.
Derive the current status from the event payload (timestamps, resource state), not from the event order.
Design handlers to be idempotent and resilient to out-of-order messages.
Store events as data points and replay them in your system if needed.

Fault tolerance

We will make a best effort to deliver webhook events reliably. In cases where delivery to your endpoint does not succeed, our system will retry sending the event. Retries apply only to 5xx responses and network errors. 2xx and 4xx responses are final and are never retried. Each event gets up to 5 delivery attempts in total — the initial attempt plus 4 retries — with an exponentially increasing delay between them:

Attempt	Delay after the previous failure
1	0s (immediate)
2	1 minute
3	2 minutes
4	4 minutes
5	8 minutes

If the 5th attempt also fails, the event is marked as failed and is not retried again. Because retries can span roughly 15 minutes, a recovering endpoint may receive an event well after the action that triggered it.

Event handler recommendations

Idempotency In general we recommend that the endpoint implementation is idempotent and resilient to temporary delivery delays.
Response time: Your server should respond within 15 seconds. Requests that exceed this time will be treated as failed.
Asynchronous Processing: Your endpoint should return a 2xx response as quickly as possible to acknowledge receipt of the event. Avoid performing heavy or time-consuming operations (e.g., database writes, external API calls) before sending this acknowledgement. If additional work is required, enqueue it for asynchronous processing after the acknowledgement has been sent.

Security and Verification

SSL Certificates

Your webhook’s server requires a valid SSL certificate in order to receive events from Nitro.

Signature Headers

Nitro signs webhook events using cryptographic signatures to guarantee their authenticity and integrity, following the RFC 9421 standard. To validate an event, generate a cryptographic signature using the event headers together with your client secret key and then compare this signature with the one included in the event headers. Matching signatures confirm that the event originated from Nitro and that its contents have not been altered. Follow these steps to implement signature validation:

Extract data from headers

The event will include these three headers:

- Content-Digest: sha-256=:<base64-of-body-hash>:
- Signature-Input: sig1=("@method" "@path" "host" "date" "content-digest");
keyid="clientId"; alg="hmac-sha256"; created=1758022496
- Signature: sig1=:Lve95gjOVATpfV8EL5X4nxwjKHE=:

Where:

Content-Digest: A SHA-256 hash of the request body, base64-encoded.
Signature-Input: Signature parameters and metadata of signing method.
Signature: The cryptographic signature you will later compare.

Construct a canonical representation

Using the header data, build a canonical representation of the signed components as a single continuous string, making sure to follow the exact order defined in the Signature-Input header.

"@method": POST (the HTTP method)
"@path": /your-webhooks-endpoint (the URL path)
"host": customer-service (the host header value)
"date": Tue, 15 Sep 2025 12:34:56 GMT (The date header value, as a timestamp in RFC 1123 format)
"content-digest": sha-256=:uoqx...abc=: (the same hash from Content-Digest header)
"@signature-params": ("@method" "@path" "host" "date" "content-digest");

At the end, append a line for signature parameters (created, keyid, alg) as per RFC 9421.

created=<created>; keyid=<keyid>; alg=<alg> (metadata about the signature)

The final result should look like this::

"@method": POST
"@path": /your-webhooks-endpoint
"host": customer-service
"date": Tue, 15 Sep 2025 12:34:56 GMT
"content-digest": sha-256=:uoqx...abc=:
"@signature-params": ("@method" "@path" "host" "date" "content-digest");
created=1758022496; keyid="clientId"; alg="hmac-sha256"

When writing the string in code, represent line breaks with \n. For example:

signature_base = '"@method": POST\n"@path": /your-webhooks-endpoint\n"host": customer-service\n"date": Tue, 15 Sep 2025 12:34:56 GMT\n"content-digest": sha-256=:uoqx...abc=:\n"@signature-params": ("@method" "@path" "host" "date" "content-digest"); created=1758022496; keyid="clientId"; alg="hmac-sha256"'

Apply Canonicalization rules (format the string)

The string must be formatted according to strict rules below. Any deviation will produce a different signature. Once formatted, the result is called the signature_base_string, which will be the dynamic portion of the cryptographic signature.

Convert all header names to lowercase.
Remove leading/trailing whitespace from values.
Normalize internal whitespace.
If a header has multiple values, join them with commas.
Maintain the exact order specified in Signature-Input.

Generate signature

With the signature_base_string ready, apply the following formula in your code to generate the expected signature:expected_signature = base64encode(hmac_sha256(your_secret_key, signature_base_string))

Compare signature values

Compare the signature you generated with the value in the Signature header. A match confirms that the event is authentic and that its contents have not been altered.

Start Here

PDF Services

Sign API

Reference

Overview

How to register a webhook

Editing a webhook

Deleting a webhook

After Registration

Handling Events

Event Payload

Event Types

Webhook’s Response

Backwards Compatibility

Event Ordering

Fault tolerance

Event handler recommendations

Security and Verification

SSL Certificates

Signature Headers

​Overview

​How to register a webhook

​Editing a webhook

​Deleting a webhook

​After Registration

​Handling Events

​Event Payload

​Event Types

​Webhook’s Response

​Backwards Compatibility

​Event Ordering

​Fault tolerance

​Event handler recommendations

​Security and Verification

​SSL Certificates

​Signature Headers

Overview

How to register a webhook

Editing a webhook

Deleting a webhook

After Registration

Handling Events

Event Payload

Event Types

Webhook’s Response

Backwards Compatibility

Event Ordering

Fault tolerance

Event handler recommendations

Security and Verification

SSL Certificates

Signature Headers