# Docusign Logs ## Overview Panther supports ingesting [Docusign](https://www.docusign.com/) Connect webhook events through HTTP. [Docusign Connect](https://developers.docusign.com/platform/webhooks/connect/) allows you to configure webhooks that notify external applications like Panther when specific events in your eSignature workflows occur. Docusign Connect webhooks can provide real-time notifications about various entities, e.g. envelopes (being sent, delivered, completed, or voided), recipients, templates, indentity verifications, and more. See a [full list of available event triggers here](https://developers.docusign.com/platform/webhooks/connect/event-triggers/). You can the Docusign logs integration in Panther to: * **Detect unauthorized access and fraud**: Track failed authentication attempts, suspicious recipient behavior, unusual signing patterns, and unexpected envelope modifications * **Monitor template security**: Monitor creation, modification, or deletion of document templates * **Monitor account activity**: Track administrative actions and configuration changes ### Docusign event triggers commonly used for security monitoring The following [event triggers](https://developers.docusign.com/platform/webhooks/connect/event-triggers/) are commonly used for security monitoring: * `recipient-authentication-failure`: Authentication failures * `envelope-voided`: Envelope cancellations (potential fraud) * `envelope-corrected`: Document corrections (potential tampering) * `template-created`, `template-modified`, `template-deleted`: Template changes * `recipient-declined`: Document refusals ## How to onboard Docusign logs to Panther ### Prerequisite * To configure Docusign Connect webhooks, you must have administrative privileges in your Docusign account. See the [Docusign Connect documentation](https://developers.docusign.com/platform/webhooks/connect/) for more information. ### Step 1: Create a new Docusign source in Panther 1. In the left-hand navigation bar of your Panther Console, click **Configure** > **Log Sources**. 2. Click **Create New**. 3. Search for "Docusign," then click its tile. 4. Click **Start Setup**.
An arrow is drawn from a tile labeled "Docusign" to a "Start Setup" button.
5. Follow Panther's [instructions for configuring an HTTP Source](https://docs.panther.com/data-transports/http#how-to-set-up-an-http-log-source-in-panther), beginning at Step 5. * During setup, for the **Auth method**, you will be required to use either **Basic Authentication** or **HMAC**. * If you select **HMAC**, for **Header Name**, enter `X-Docusign-Signature-1`. [Learn more about using HMAC for Connect webhooks here](https://developers.docusign.com/platform/webhooks/connect/hmac/). * Save the authentication details you configure, as you'll need them in the next step, when setting up the webhook in Docusign. * Payloads sent to this source are subject to the [payload requirements for all HTTP sources](https://docs.panther.com/data-transports/http#payload-requirements). * Do not proceed to the next step until the creation of your HTTP endpoint has completed. ### Step 2: Configure a Docusign Connect webhook Configure a Docusign Connect webhook by following the steps below. If you need extra support during this process, please see [the Docusign Create a Connect Configuration documentation](https://support.docusign.com/s/document-item?language=en_US&_gl=1*jyc3me*_gcl_au*MTM1MDY1NDYyMS4xNzUzODgzNTcx\&bundleId=vob1727899215236\&topicId=xwi1583277389681.html&_LANG=enus). 1. Log in to your Docusign account as an administrator. 2. In the navigation bar, click **Integrations** > **Connect**. 3. Click **Add Configuration** > **Custom**. 4. Configure the [webhook Connect fields](https://support.docusign.com/s/document-item?language=en_US\&bundleId=vob1727899215236\&topicId=zjq1665170940873.html&_LANG=enus): * **Name**: Enter a descriptive name, e.g., `Panther Security Integration`. * **URL to Publish**: Enter the **HTTP Source URL** you generated in Panther in Step 1. * **Trigger Events**: Select the [event triggers](https://developers.docusign.com/platform/webhooks/connect/event-triggers/) you want to monitor. * **Include Data**: For each category, select the fields you'd like to be included in the events sent to Panther. Learn about these fields in this [Docusign documentation](https://support.docusign.com/s/document-item?language=en_US\&bundleId=vob1727899215236\&topicId=zbg1608069790210.html&_LANG=enus). {% hint style="warning" %} For **Envelope** and **Recipient** events, it's recommended to leave **Documents** and **Attachments** unchecked. This helps to reduce payload size, which can prevent potential event delivery delays. Learn more about [how to retrieve documents via the eSignature API instead here](https://support.docusign.com/s/document-item?language=en_US&_gl=1*jyc3me*_gcl_au*MTM1MDY1NDYyMS4xNzUzODgzNTcx\&bundleId=vob1727899215236\&topicId=oza1583277387805.html&_LANG=enus). {% endhint %} * **Include HMAC Signature**: Check this if you used HMAC authentication in Panther in Step 1. * In the **1.** field, enter the HMAC **Header Name** you entered in Panther in Step 1. Docusign will send this value associated to the `X-Docusign-Signature-1` header. * Learn more in the [Docusign Using HMAC Security with Docusign Connect documentation](https://developers.docusign.com/platform/webhooks/connect/hmac/).
Under an 'Integration and Security Settings' header is an 'Include HMAC Signature (Recommended)' checkbox. Beneath, there is a field under a 'Key' header that is circled.
* **Include Basic Authentication Header**: Check this if you used basic authentication in Panther in Step 1. * **User Name**: Enter the **Username** you entered in Panther in Step 1. * **Password**: Enter the **Password** you entered in Panther in Step 1. 5. Click **Add configuration**. ## Supported log types ### Docusign.Connect Docusign Connect webhook events that notify about envelope status changes, recipient actions, document workflow updates, and more. Reference: [Docusign Connect JSON SIM Event Model](https://developers.docusign.com/platform/webhooks/connect/json-sim-event-model/) ```yaml schema: Docusign.Connect description: Docusign Connect webhook events that notify about envelope status changes, recipient actions, and document workflow updates referenceURL: https://developers.docusign.com/platform/webhooks/connect/json-sim-event-model fields: - name: event required: true description: The type of event that triggered the webhook (e.g., recipient-sent, envelope-completed). type: string - name: uri description: The REST API URI for the envelope resource. type: string - name: retryCount description: Number of retry attempts for this webhook delivery. type: string - name: configurationId description: The Connect configuration ID that generated this webhook. type: string - name: apiVersion description: The Docusign API version used for this event. type: string - name: generatedDateTime required: true description: When the event was generated by Docusign. type: timestamp timeFormats: - rfc3339 isEventTime: true - name: data required: true description: The main event data containing event information. type: object fields: - name: accountId description: Identifies the sender's account or, for Recipient Connect, identifies the recipient's account. type: string indicators: - trace_id - name: userId description: The related User ID with the event type: string indicators: - trace_id - name: recipientId description: The recipient id related to this event type: string indicators: - trace_id - name: envelopeId description: Identifies the envelope involved in the event. type: string indicators: - trace_id - name: name description: The name of the related template event or the name of the person who the envelope is reassigned to. type: string - name: email description: The email address of the person who the envelope is reassigned to. type: string indicators: - email - name: routingOrder description: The routing order of the person who the envelope is reassigned to. type: string - name: created description: The UTC date and time when the template was created/edited/deleted. type: timestamp timeFormats: - rfc3339 - name: templateId description: The template ID that was created/edited/deleted. type: string indicators: - trace_id - name: clickwrapId description: Identifies the elastic template that was agreed or declined. type: string indicators: - trace_id - name: agreementId description: Identifies the agreement within the elastic template. type: string indicators: - trace_id ``` ## Custom detection patterns When writing custom detections for Docusign, you can use these common patterns: ```python # Check for specific event types event_type = event.get('event') # Monitor for authentication failures if event_type == 'recipient-authentication-failure': return True # Monitor for envelope voiding (potential fraud indicator) if event_type == 'envelope-voided': return True ``` ```python # Access envelope and sender/recipient data envelope_id = deep_get(event, 'data', 'envelopeId') account_id = deep_get(event, 'data', 'accountId') ``` ## Querying Docusign logs To query Docusign logs in [Data Explorer](https://docs.panther.com/search/data-explorer): ```sql -- View recent Docusign events SELECT event, generatedDateTime, data:envelopeId, data:email FROM panther_logs.docusign_connect WHERE p_occurs_since('1 day') ORDER BY p_event_time DESC; -- Monitor authentication failures SELECT * FROM panther_logs.docusign_connect WHERE event = 'recipient-authentication-failure' AND p_occurs_since('7 days') ORDER BY p_event_time DESC; -- Track envelope status changes SELECT event, data:envelopeId, data:accountId, generatedDateTime FROM panther_logs.docusign_connect WHERE event LIKE 'envelope-%' AND p_occurs_since('1 day') ORDER BY generatedDateTime DESC; ```