Skip to main content
Webhook support is not yet available. It will be introduced in an upcoming release.

​
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 an webhook

Webhook URLs are registered in the global admin user interface, along with the events you want to enable for tracking. One Webhook is permited per application. Follow these steps to set it up:
The steps to register a webhook and events will be detailed in future updates to this documentation

​
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 The webhook registration UI includes a Send Test Event button. Use it as a ping tool to verify that your webhook is responsive before enabling event tracking in production.

​
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.
  • 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.
The envelope has been created.
    {
        "id": "<event_id>",
        "type": "EnvelopeCreated",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            }
        }
    }
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"
            }
        }
    }
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>"
            }
        }
    }
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>" }
            ]
        }
    }
The envelope has been cancelled by the owner.
    {
        "id": "<event_id>",
        "type": "EnvelopeCancelled",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            }
        }
    }
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": {}
        }
    }
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>"
            }
        }
    }
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
            }
        }
    }
All participants have signed and sealing will start.
    {
        "id": "<event_id>",
        "type": "EnvelopeSigningCompleted",
        "created": "<created_timestamp>",
        "data": {
            "envelope": {
                "id": "<envelope_id>",
                "name": "<envelope_name>"
            }
        }
    }
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>"
            }
        }
    }

​
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 Sign 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:
  1. EnvelopeSigningComplete
  2. 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.
Specific retry mechanisms will be detailed in future updates to this documentation

​
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:
1

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.
2

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.
1. "@method": POST (the HTTP method)
2. "@path": /your-webhooks-endpoint (the URL path)
3. "host": customer-service (the host header value)
4. "date": Tue, 15 Sep 2025 12:34:56 GMT (The date header value, as a timestamp in RFC 1123 format)
5. "content-digest": sha-256=:uoqx...abc=: (the same hash from Content-Digest header)
6. "@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"'
3

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.
4

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))
5

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.
⌘I