Understanding Webhook Context: Identifying Actors and State Changes in Document and Template Events

BoldSign webhook payloads now include richer context so you can tell who initiated an action, what changed, and which signer (if any) caused the event. The same context format is provided for both document and template webhooks.

When BoldSign delivers webhook notifications, the payload will include an object called context. This object provides additional clarity about:

• Who initiated the event
• What data changed before the event occurred

The context object allows integrations to respond intelligently without performing additional API calls.

Webhook Payload Structure

A webhook payload typically contains three primary sections:

{
"event": {
        "id": "event-uuid",
        "eventType": "Signed",
        "created": 1234567890,
        "environment": "Live"
   },
"context": {
        "eventType": "Signed",
        "actor": {
            "userType": "Signer",
            "id": "signer-1"
        },
        "previousState": {
        "signerDetails": [             
                {
                    "id": "signer-1",
                    "status": "NotCompleted"
                }
           ]
        }
    },
"data": {
        // Current state
    }
}

• event → Metadata about the webhook event
• context → Information about the triggering actor and changed values
• data → The current state of the document or template

Context Object Properties

1. eventType

• Type: String (Enum)
• Represents the webhook event that occurred.
• Mirrors the value of event.eventType.

Example values include: - Sent - Viewed - Signed - Completed - Declined - Expired - ReminderSent

2. actor

The actor object identifies who performed the action that triggered the webhook.

"actor": {
  "userType": "Signer",
  "id": "signer-1"
}

userType

Possible values:

• Sender
• Signer
• Cc
• Creator
• Admin
• SenderIdentity

id

The meaning of id depends on userType:

This ID can be correlated with objects in the data section.

Important Notes About actor

• Treat actor.id as an opaque string identifier.
• Always interpret actor.id together with actor.userType.
• context.actor can be null for system-triggered events (e.g., Completed, automatic reminders, scheduled actions).
• For Signer/Cc types, the ID is the entity ID — NOT the email address.
• For view events, rely on context.actor rather than inferring from document state.
• For reminder events:
  • context.actor identifies who triggered the reminder (Sender/Admin).
  • To identify which signers were reminded, compare:
    • context.previousState.signerDetails[]
    • data.signerDetails[]

3. previousState

The previousState object appears only when data was modified before the event was triggered. It contains only the fields that changed, along with their previous values.

Example:

"previousState": {
  "signerDetails": [
    {
      "id": "signer-1",
      "status": "NotCompleted"
    }
  ]
}

If no data was modified, previousState may be null.

What to Expect in previousState

Scalar Changes

If a simple value changes (e.g., document status):

• Only the changed key appears.

Nested Object Changes

If nested properties change:

• Only changed subfields are included.

Collection Changes

For arrays (e.g., signerDetails):

• Includes diff objects with:
  • Identifier + changed fields
• Document signer diffs use:
  • signerDetails[].id
• Template role diffs use:
  • signerDetails[].roleIndex

Add-Only Changes

If a value is newly added and had no previous value:

• previousState may not include entries.

Date/Time Fields

• Serialized as Unix timestamps (seconds).

When previousState Is Null or Empty

• previousState is null when diff processing is not performed.
• previousState may be {} (empty object) when:
  • No previous values are emitted
  • Add-only changes occurred
  • The differ detects no changes

Supported Event Types

Refer to this documentation for available document and template webhook events: Available Webhook Events

The context object is available for all Document and Template webhook events, except the following failure events (these currently do not include context):

• SendFailed
• EditFailed
• TemplateCreateFailed
• TemplateSendFailed

Recommended Implementation Approach

1. Validate the webhook signature before processing.
2. Confirm whether context exists and is not null.
3. Use eventType for routing logic.
4. Use actor.userType and actor.id for actor-specific processing.
5. Compare previousState with data when present to detect field-level changes.
6. Ensure your logic gracefully handles cases where context is null.

Practical Use Cases

• Audit logging (identify exactly who performed an action)
• Workflow automation based on actor type
• Conditional notifications triggered by specific change

Summary

The Webhook Event Context enhances BoldSign webhook payloads by providing:

• Actor identification
• Event confirmation alignment with metadata

By leveraging the context object, applications can implement more precise automation, auditing, and workflow handling while reducing redundant API requests.