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

# Webhooks guide

> Learn how to set up and use webhooks to automatically download executed documents.

## Overview

Webhooks allow your application to receive real-time notifications about events that occur within our system, such as when a document is signed or a package is fully executed.
This guide will walk you through the process of subscribing to webhooks to automatically download signed documents.

## Steps

<Steps titleSize="h3">
  <Step title="Setup a webhook endpoint">
    Follow the [Webhooks setup guide](/v4/webhooks/setup).
  </Step>

  <Step title="Handle incoming webhook event notifications">
    When a webhook event occurs, our system will send a POST request to your specified endpoint with details about the event.

    <Tabs>
      <Tab title="Package executed">
        When a package is fully executed, all documents signed by all signers, you will receive a webhook event with the following payload:

        ```json Payload highlight={2,3} theme={null}
        {
            "action": "package_executed",
            "packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
            "externalData": null,
            "eventId": "0ea12600-85bc-46dd-af85-f82f621c1abc",
            "eventOwnerOrganizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
            "eventOwnerMemberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
            "eventTime": "2022-02-23T20:20:15.9714327Z"
        }
        ```
      </Tab>

      <Tab title="Document executed">
        When a document is fully executed, signed by all signers, you will receive a webhook event with the following payload:

        ```json Payload highlight={2,3} theme={null}
        {
            "action": "document_executed",
            "packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
            "documentId": "73f34799-c3a2-49e3-aa5f-33b0c2c1f111",
            "externalId": null,
            "eventId": "8977f701-480a-4a5d-9bad-87d87fe38447",
            "eventTime": "2022-02-23T20:20:15.9021584Z"
        }
        ```
      </Tab>

      <Tab title="Document signed">
        When a document is signed by a signer, you will receive a webhook event with the following payload:

        ```json Payload highlight={2,3} theme={null}
        {
            "action": "document_signed",
            "packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
            "documentId": "73f34799-c3a2-49e3-aa5f-33b0c2c1f111",
            "revisionId": "ecaac2dc-8fe2-48fd-b3d5-74646435b1d2",
            "signerId": "d5397c13-5dcf-4574-b94b-5addf95c91df",
            "nextSignerId": "f700fdfa-b493-467e-b30d-7eb17e2bb769",
            "externalId": null,
            "eventId": "f3a27f18-b892-4c4d-8ffa-81f2f459017f",
            "eventOwnerOrganizationId": "24261ee6-5f66-4692-ba49-533c9b58999b",
            "eventOwnerMemberId": "3e09a4ce-577c-492c-ba7c-c1ebf825f9b5",
            "eventTime": "2022-02-23T20:19:56.8208742Z"
        }
        ```
      </Tab>
    </Tabs>

    Depending on your application's needs, you can handle these events accordingly. For example, when you receive a `package_executed` event,
    you can trigger the download of all executed documents in that package.

    <Tip>
      You can set `externalData` at the package level when creating a package to help correlate webhook events with your internal records.

      You can also set an `externalId` at the document level when uploading files to add to a package.

      See the [External data guide](/v4/guides/external-data) for more information.
    </Tip>
  </Step>

  <Step title="Verify webhook requests">
    To ensure that incoming webhook requests are legitimate, you should verify the signature included in the `X-Syngrafii-Signature` header of each request.

    View the [Webhooks verification guide](/v4/webhooks/setup#verify-webhooks) for detailed instructions on how to verify webhook signatures.
  </Step>

  <Step title="Get package status">
    Once you receive a webhook event you want to act on, such as the `package_executed` webhook event,
    call the [Packages status API](/v4/api/packages/status) endpoint to get the list of documents in the package.

    ```http Request theme={null}
    GET /packages/{packageId}/status
    ```

    ```json Response highlight={7} theme={null}
    {
        "packageId": "24428e41-8b96-40cc-96e6-b74c7c539fcb",
        ...
        "state": "executed",
        "documents": [
            {
                "documentId": "73f34799-c3a2-49e3-aa5f-33b0c2c1f111",
                ...
            }
        ],
        ...
    }
    ```
  </Step>

  <Step title="Download executed documents">
    After confirming that the package is fully executed, you can use the [Packages download API](/v4/api/packages/download) endpoint to download all executed documents in the package.

    <Tip>
      Use the package status response to determine all the document IDs to download.
    </Tip>

    #### Download PDFs

    <Tabs>
      <Tab title="Executed">
        ```http Request theme={null}
        GET /packages/{packageId}/documents/{documentId}/pdf/executed/download
        ```
      </Tab>

      <Tab title="CAC">
        ```http Request theme={null}
        GET /packages/{packageId}/documents/{documentId}/pdf/cac/download
        ```
      </Tab>

      <Tab title="MasterFile">
        ```http Request theme={null}
        GET /masterfiles/{packageId}/pdf/download
        ```

        See the [MasterFile download API](/v4/api/masterfile/download) for more information on downloading MasterFiles.
      </Tab>
    </Tabs>
  </Step>
</Steps>