> ## Documentation Index
> Fetch the complete documentation index at: https://developers.gonitro.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Guide

<Warning>Webhook support is not yet available. It will be introduced in an upcoming release.</Warning>

## 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:

<Note>The steps to register a webhook and events will be detailed in future updates to this documentation</Note>

### 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:

<CodeGroup>
  ```json JSON theme={null}
  {
    "id": "<string>",
    "type": "<string>",
    "created": "<string>",
    "data": {...}
  }
  ```
</CodeGroup>

* `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.

<AccordionGroup>
  <Accordion title="EnvelopeCreated">
    The envelope has been created.

    ```json theme={null}
        {
            "id": "<event_id>",
            "type": "EnvelopeCreated",
            "created": "<created_timestamp>",
            "data": {
                "envelope": {
                    "id": "<envelope_id>",
                    "name": "<envelope_name>"
                }
            }
        }
    ```
  </Accordion>

  <Accordion title="EnvelopeDocumentAdded">
    A document has been uploaded and attached to the envelope.

    ```json theme={null}
        {
            "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"
                }
            }
        }
    ```
  </Accordion>

  <Accordion title="EnvelopeDocumentDeleted">
    A document has been deleted from an envelope.

    ```json theme={null}
        {
            "id": "<event_id>",
            "type": "EnvelopeDocumentDeleted",
            "created": "<created_timestamp>",
            "data": {
                "envelope": {
                    "id": "<envelope_id>",
                    "name": "<envelope_name>"
                },
                "document": {
                    "id": "<document_id>"
                }
            }
        }
    ```
  </Accordion>

  <Accordion title="EnvelopeSentForSignature">
    An envelope has been sent for signature.

    ```json theme={null}
        {
            "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>" }
                ]
            }
        }
    ```
  </Accordion>

  <Accordion title="EnvelopeCancelled">
    The envelope has been cancelled by the owner.

    ```json theme={null}
        {
            "id": "<event_id>",
            "type": "EnvelopeCancelled",
            "created": "<created_timestamp>",
            "data": {
                "envelope": {
                    "id": "<envelope_id>",
                    "name": "<envelope_name>"
                }
            }
        }
    ```
  </Accordion>

  <Accordion title="SignatureRequestReassigned">
    A signature request has been forwarded to another participant.

    ```json theme={null}
        {
            "id": "<event_id>",
            "type": "SignatureRequestReassigned",
            "created": "<created_timestamp>",
            "data": {
                "envelope": {
                    "id": "<envelope_id>",
                    "name": "<envelope_name>"
                },
                "signature": {}
            }
        }
    ```
  </Accordion>

  <Accordion title="SignatureRequestDeclined">
    A signature request has been declined.

    ```json theme={null}
        {
            "id": "<event_id>",
            "type": "SignatureRequestDeclined",
            "created": "<created_timestamp>",
            "data": {
                "envelope": {
                    "id": "<envelope_id>",
                    "name": "<envelope_name>"
                },
                "signature": {
                    "declinedBy": "<participant_email>"
                }
            }
        }
    ```
  </Accordion>

  <Accordion title="SignatureRequestSigned">
    A participant has signed the envelope.

    ```json theme={null}
        {
            "id": "<event_id>",
            "type": "SignatureRequestSigned",
            "created": "<created_timestamp>",
            "data": {
                "envelope": {
                    "id": "<envelope_id>",
                    "name": "<envelope_name>"
                },
                "signature": {
                    "signedBy": "<participant_email>",
                    "order": 1
                }
            }
        }
    ```
  </Accordion>

  <Accordion title="EnvelopeSigningCompleted">
    All participants have signed and sealing will start.

    ```json theme={null}
        {
            "id": "<event_id>",
            "type": "EnvelopeSigningCompleted",
            "created": "<created_timestamp>",
            "data": {
                "envelope": {
                    "id": "<envelope_id>",
                    "name": "<envelope_name>"
                }
            }
        }
    ```
  </Accordion>

  <Accordion title="EnvelopeSealed">
    The envelope is sealed and digitally signed. No further changes can be made.

    ```json theme={null}
        {
            "id": "<event_id>",
            "type": "EnvelopeSealed",
            "created": "<created_timestamp>",
            "data": {
                "envelope": {
                    "id": "<envelope_id>",
                    "name": "<envelope_name>"
                }
            }
        }
    ```
  </Accordion>

  <Accordion title="OwnerMessaged">
    The owner received a message from one of the signers.

    ```json theme={null}
        {
            "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>"
            }
        }
    ```
  </Accordion>
</AccordionGroup>

### 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:

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.

<Note>Specific retry mechanisms will be detailed in future updates to this documentation</Note>

#### 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](https://datatracker.ietf.org/doc/rfc9421/).

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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.

    ```text theme={null}
    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::

    ```text theme={null}
    "@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:

    ```python theme={null}
    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"'
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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))`
  </Step>

  <Step title="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.
  </Step>
</Steps>