Inline Webhook Configuration

Overview

This guide explains how to configure and use inline webhooks to receive real-time notifications for various events in the e-signature and e-notary system.

Configuration Structure Example

{
  "urlToPublish": "https://your-endpoint.com/webhook",
  "triggerEvents": ["EVENTS.ALL"],
  "requestedArtifacts": [
    {
      "artifactKind": "COMPLETED_PACKAGE",
      "metadata": {}
    }
  ]
}

Configuration Properties

`urlToPublish`

Type: string (URI format)
Required: Yes
Description: The HTTPS endpoint where webhook events will be published
Requirements: Must be a valid HTTPS URL

`triggerEvents`

Type: array
Required: Yes
Description: List of events that will trigger the webhook, including the following special
- EVENTS.ALL: Subscribe to all available events
- EVENTS.E_NOTARY_PACKAGE.AUTH_OUTCOME_UPDATED: Notary package authentication outcomes

`requestedArtifacts`

Type: array
Required: No
Description: List of artifacts to include in the webhook payload

Structure:

{
  artifactKind: string;  // Type of artifact to request
  metadata: object;      // Optional configuration for the artifact
}

Event Types

Special Events

Event Name	Description
`EVENTS.ALL`	Subscribes to all available events
`EVENTS.E_NOTARY_PACKAGE.AUTH_OUTCOME_UPDATED`	Notary package authentication outcomes

ESignature Events

Event	Description
`ACTIVATED`	eSignature package has been activated
`CANCELLED`	eSignature package process has been cancelled
`COMPLETED`	All signatures have been collected
`DECLINED`	eSignature package has been declined by a signer
`DELIVERY_FAILED`	Failed to deliver document
`DISABLE_RECORDING`	Recording has been disabled
`ENABLE_REPEAT_ENTRIES`	Repeat entries have been enabled
`DISABLE_REPEAT_ENTRIES`	Repeat entries have been disabled
`ENABLE_RECORDING`	Recording has been enabled
`LIVE_EDITING_STARTED`	Live editing session started
`LIVE_EDITING_FINISHED`	Live editing session completed
`JOINT_SIGNERS_GROUP_CREATED`	Group of joint signers created
`JOINT_SIGNERS_GROUP_REMOVED`	Group of joint signers removed
`LIVE_STARTED`	Live signing session started
`LIVE_ENDED`	Live signing session ended
`LOCKED_FOR_REVIEW`	eSignature package locked for review
`UNLOCKED_FROM_REVIEW`	eSignature package unlocked from review
`OBSERVER_INVITED`	Observer has been added
`OBSERVER_REMOVED`	Observer has been removed
`PREPARED`	eSignature package has been prepared for signing
`REDRAFTED`	eSignature package has been redrafted
`REMINDER`	Reminder sent to signer
`REMINDER_BY_TEXT_MESSAGE`	SMS reminder sent
`RESCHEDULED`	eSignature package schedule has been modified
`SENT`	eSignature package has been sent to signers
`SCHEDULED`	eSignature package has been scheduled
`SIGNED`	eSignature package has been signed
`SIGNER_ADDED`	New signer has been added
`SIGNER_REMOVED`	Signer has been removed
`TRANSFERRED`	eSignature package ownership has been transferred
`VIEWED`	eSignature package has been viewed by a recipient

Available Artifacts

E-Signature Package Artifacts

Artifact	Description
`COMPLETED_PACKAGE`	The final signed document package
`E_NOTARY_JOURNAL`	Electronic notary journal entries
`E_SIGNATURE_AUDIT_TRAIL`	Complete audit trail of the signing process
`IDV_AUDIT_TRIALS`	Identity verification audit trails

Webhook Payload

When a webhook is triggered, it sends a POST request to your endpoint with the following payload structure:

Standard Payload Structure

{
  id: string;              // E-Signature Package ID
  title: string;           // E-Signature Package title
  status: string;          // Current status of the package
  signers: Array<{         // Array of signers
    id: string;
    email: string;
    status: string;
    // Additional signer details
  }>;
  ccRecipients: Array<{    // Array of CC recipients
    email: string;
    // Additional recipient details
  }>;
  kind: string;            // Type of package
  eNotaryPackageId?: string; // ID of associated e-notary package if applicable
  webhookEvent: string;    // The event that triggered the webhook
  webhookArtifactResultants: Array<{
    // Requested artifacts based on configuration
    kind: string;
    data: any;
  }>;
}

Special Event Payloads

For `EVENTS.E_NOTARY_PACKAGE.AUTH_OUTCOME_UPDATED`

The payload is of ENotaryPackage, if you'd like to determine whether a signer has completed all their notifications, you can check the validationResponses with respect to the validationRequests.

{
  // ... standard payload fields ...
  eNotaryPackage: {
  "id": "string",
  "isTestMode": true,
  "ownerId": "string",
  "eSignaturePackageId": "string",
  "validationRequests": [
    {
      "signerId": "string",
      "idv": {
        "enforcementCriterion": "REQUIRED"
      },
      "kba": {
        "enforcementCriterion": "REQUIRED"
      },
      "locationVerification": {
        "enforcementCriterion": "REQUIRED"
      },
      "vulnerabilityScreening": {
        "enforcementCriterion": "REQUIRED"
      }
    }
  ],
  "validationResponses": [
    {
      "signerId": "string",
      "idv": {
        "id": "string",
        "outcome": "PASSED"
      },
      "kba": {
        "id": "string",
        "outcome": "PASSED"
      },
      "locationVerification": {
        "id": "string",
        "outcome": "PASSED"
      },
      "vulnerabilityScreening": {
        "id": "string",
        "outcome": "PASSED"
      }
    }
  ]
}

Webhook Artifacts Response Structure

COMPLETED_PACKAGE

{
  kind: "COMPLETED_PACKAGE",
  data: {
    // Package data including documents and metadata
  }
}

E_NOTARY_JOURNAL

{
  kind: "E_NOTARY_JOURNAL",
  data: {
    // Journal entries and related metadata
  }
}

E_SIGNATURE_AUDIT_TRAIL

{
  kind: "E_SIGNATURE_AUDIT_TRAIL",
  data: {
    // Detailed audit trail information
  }
}

IDV_AUDIT_TRIALS

{
  kind: "IDV_AUDIT_TRIALS",
  data: {
    // Identity verification audit data
  }
}

Example Configurations

Subscribe to All Events

{
  "urlToPublish": "https://api.example.com/webhooks",
  "triggerEvents": ["EVENTS.ALL"],
  "requestedArtifacts": [
    {
      "artifactKind": "COMPLETED_PACKAGE",
      "metadata": {}
    }
  ]
}

Specific Events with Multiple Artifacts

{
  "urlToPublish": "https://api.example.com/webhooks/esignature",
  "triggerEvents": [
    "SIGNED",
    "COMPLETED",
    "EVENTS.E_NOTARY_PACKAGE.AUTH_OUTCOME_UPDATED"
  ],
  "requestedArtifacts": [
    {
      "artifactKind": "E_SIGNATURE_AUDIT_TRAIL",
      "metadata": {}
    },
    {
      "artifactKind": "E_NOTARY_JOURNAL",
      "metadata": {}
    }
  ]
}

Example Webhook Payloads

Standard Signing Event

{
  "id": "esp_123456",
  "title": "Contract Agreement",
  "status": "COMPLETED",
  "signers": [
    {
      "id": "signer_1",
      "email": "[email protected]",
      "status": "SIGNED"
    }
  ],
  "ccRecipients": [
    {
      "email": "[email protected]"
    }
  ],
  "kind": "STANDARD",
  "webhookEvent": "SIGNED",
  "webhookArtifactResultants": [
    {
      "kind": "E_SIGNATURE_AUDIT_TRAIL",
      "data": {
        "timestamp": "2024-03-21T14:30:00Z",
        "action": "SIGNED",
        "user": "[email protected]"
      }
    }
  ]
}

E-Notary Auth Outcome Event

{
  "id": "esp_123456",
  "title": "Notarized Document",
  "status": "IN_PROGRESS",
  "signers": [
    {
      "id": "signer_1",
      "email": "[email protected]",
      "status": "PENDING"
    }
  ],
  "ccRecipients": [],
  "kind": "E_NOTARY",
  "eNotaryPackageId": "enp_123456",
  "webhookEvent": "EVENTS.E_NOTARY_PACKAGE.AUTH_OUTCOME_UPDATED",
  "eNotaryPackage": {
    "id": "enp_123456",
    "status": "AUTH_SUCCESS",
    "authenticationMethod": "ID_VERIFICATION",
    "completedAt": "2024-03-21T14:30:00Z"
  },
  "webhookArtifactResultants": [
    {
      "kind": "E_NOTARY_JOURNAL",
      "data": {
        "entryId": "nej_123456",
        "timestamp": "2024-03-21T14:30:00Z",
        "status": "COMPLETED"
      }
    }
  ]
}

Best Practices

1. Endpoint Security

Use HTTPS endpoints only
Implement authentication for your webhook endpoint
Validate webhook signatures if provided
Keep your endpoint URLs confidential

2. Event Selection

Use EVENTS.ALL only if you need all events
Subscribe to specific events when possible to reduce unnecessary traffic
Consider business needs when selecting events

3. Artifact Management

Request only necessary artifacts
Consider storage requirements for large artifacts
Implement proper artifact processing and storage
Clean up stored artifacts according to your retention policy

4. Error Handling

Implement proper error handling
Return 2xx status codes promptly
Handle webhook retries appropriately
Log all webhook events for debugging
Implement dead letter queues for failed webhook deliveries

5. Performance

Process webhook payloads asynchronously
Implement proper queueing if necessary
Monitor webhook processing times
Set up alerts for webhook processing failures
Scale your webhook processing infrastructure as needed

6. Monitoring and Maintenance

Monitor webhook delivery success rates
Set up logging for webhook events
Implement alerting for webhook failures
Regularly review and update webhook configurations
Clean up unused webhook subscriptions

Troubleshooting

Common Issues

Webhook not receiving events
- Verify webhook status is ENABLED
- Check if trigger events match expected events
- Verify endpoint URL is correct and accessible
Missing artifacts
- Verify artifact kinds are correctly specified
- Check if artifacts are available for the package type
- Ensure proper permissions are set
Authentication failures
- Verify endpoint authentication credentials
- Check if SSL/TLS certificates are valid
- Ensure proper headers are set