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

> Register a Nitro Sign webhook to receive real-time envelope, document and signature events over HTTP POST, and verify their signatures.

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.

<Note>
  Looking for per-request notifications on asynchronous PDF Services jobs instead?
  See [Callbacks](/docs/build-nitro/pdf-services-callbacks). The two mechanisms are
  configured differently and are not interchangeable.
</Note>

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

<Steps>
  <Step title="Open your application">
    In the Admin Portal, go to your API Application's details and select **Add Webhook**.
  </Step>

  <Step title="Enter your endpoint URL">
    Enter your webhook URL. You can select **Test Webhook** at this point to confirm your endpoint is reachable before continuing.
  </Step>

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

  <Step title="Save your client secret">
    On creation, Nitro generates a client secret for your webhook.

    <Note>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.</Note>

    Your client secret is used to verify incoming event signatures. See [Security and Verification](#security-and-verification).
  </Step>
</Steps>

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

<Note>Deleting a webhook does not affect past deliveries or in-flight retries already queued at the time of deletion.</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**
  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:

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

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

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](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>