Event Context

The context object is part of the webhook payload that provides information about who triggered the event and what changed in the resource. It enables precise actor identification and granular change detection without additional API calls.

This feature is currently in beta. The structure, behavior, and properties may evolve based on developer feedback until it reaches a stable release.

The context object includes two key components:

1. context.actor - Identifies who triggered the event with precise role information
2. context.previousState - Provides the previous values of fields that changed

Capabilities:

• Identify which specific signer signed a document in a Signed event
• Determine exactly what changed in an Edited event
• Know who viewed a document in a Viewed event
• Identify to which signer a reminder was sent in a Reminder event
• Update only affected resources (e.g., specific signer's status)
• Track field-level changes for auditing
• Send targeted notifications to relevant parties

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

Context for Sender Identity and Identity Verification events is planned for future releases.

Important: The context object is only populated for documents and templates created on or after January 08, 2026.

• Documents/templates created before this date will have context set to null
• This limitation is permanent, even if older resources are updated after January 08, 2026
• Your webhook handler must handle both scenarios: with context (new resources) and without context (older resources)

The context object is a top-level property in the webhook payload:

{
    "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
    }
}

1. Route by event type using event.eventType or context.eventType
2. Identify the actor using context.actor
3. Detect changes using context.previousState
4. Compare states by examining previousState against current data values

previousState contains only changed fields with their previous values (diff-based approach).

The eventType property identifies the webhook event type.

• Type: String enum
• Values: Sent, Signed, Completed, etc.
• Behavior: Mirrors event.eventType

The actor object identifies who performed the action.

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

Indicates the type of actor. The exact values are:

• Sender - Document/template sender
• Signer - Document signer
• Cc - CC recipient
• Creator - Template creator
• Admin - Account or team administrator
• SenderIdentity - The sender identity user (for document/template created on behalf of a sender identity)

The meaning of id depends on userType:

Important notes:

• Treat actor.id as an opaque string identifier
• Always use actor.id with actor.userType
• context.actor can be null for system-triggered events (for example, Completed, automatic reminders, and other scheduled/automated 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 (e.g., Sender/Admin). To identify which signers were reminded, use context.previousState.signerDetails[] and compare it with data.signerDetails[].

When an admin performs an action:

• actor.userType is set to Admin
• actor.id contains the admin's BoldSign user ID

Common admin actions include revoking documents, editing document settings, and viewing the document.

The previousState object provides previous values of properties modified by the event.

• Type: Object (dynamic) or null
• Behavior: Contains only changed fields
• Values: Represent the state before the event

• Scalar changes (e.g., document status): previousState includes only changed keys
• Nested object changes: previousState includes only changed subfields
• Collection changes (e.g., signerDetails): Array of diff objects with an identifier plus changed fields (document signer diffs use signerDetails[].id, template role diffs use signerDetails[].roleIndex)
• Add-only changes: May have no previousState entries (no previous value)
• Date/time fields: Serialized as Unix timestamps (seconds)

• previousState is null when diff processing is not performed
• previousState can be an empty object ({}) when no previous values are emitted (e.g., add-only changes, or when the differ detects no changes)

{
    "event": {
        "eventType": "Signed"
    },
    "context": {
        "eventType": "Signed",
        "actor": { "userType": "Signer", "id": "signer-1" },
        "previousState": {
            "signerDetails": [{ "id": "signer-1", "status": "NotCompleted" }]
        }
    },
    "data": {
        "object": "document",
        "documentId": "doc-id",
        "signerDetails": [{ "id": "signer-1", "status": "Completed" }]
    }
}

Interpretation:

• context.actor identifies which signer acted (signer-1)
• previousState.signerDetails[0] shows the previous status (NotCompleted)
• Current status is in data.signerDetails[] (Completed)

Usage: Find the signer in data.signerDetails where id == context.actor.id and this is the signer who signed the document.

{
    "context": {
        "eventType": "Viewed",
        "actor": { "userType": "Cc", "id": "cc-123" },
        "previousState": null
    },
    "data": {
        "object": "document",
        "ccDetails": [{ "id": "cc-123", "emailAddress": "cc@example.com" }]
    }
}

Usage: Match context.actor.id with data.ccDetails[].id to identify which CC recipient viewed the document.

{
    "context": {
        "eventType": "Reminder",
        "actor": { "userType": "Sender", "id": "user-123" },
        "previousState": {
            "signerDetails": [
                { "id": "signer-1", "lastReminderSentOn": null },
                { "id": "signer-2", "lastReminderSentOn": null }
            ]
        }
    },
    "data": {
        "object": "document",
        "signerDetails": [
            { "id": "signer-1", "status": "NotCompleted", "lastReminderSentOn": 1735689600 },
            { "id": "signer-2", "status": "NotCompleted", "lastReminderSentOn": 1735689600 },
            { "id": "signer-3", "status": "NotCompleted", "lastReminderSentOn": null }
        ]
    }
}

Interpretation:

• context.actor identifies who triggered the reminder action (typically Sender or Admin)
• Multiple signers may be reminded in a single event
• context.previousState.signerDetails[] contains the signers affected by this reminder action, with their previous lastReminderSentOn values
• Use the IDs in previousState.signerDetails[] to find the corresponding signers in data.signerDetails[] and process only those signers

Usage: For each entry in context.previousState.signerDetails, match the signer in data.signerDetails where id == previousSigner.id to identify and process only the signers who were reminded.

{
    "context": {
        "eventType": "TemplateEdited",
        "actor": { "userType": "Creator", "id": "actor-id" },
        "previousState": {
            "templateName": "Old Name"
        }
    },
    "data": {
        "object": "template",
        "templateName": "New Name"
    }
}

When context.actor.userType is SenderIdentity, the actor.id is the sender identity ID. You can correlate this with behalfOf.id in the document/template payload (when present).

{
    "context": {
        "eventType": "Sent",
        "actor": { "userType": "SenderIdentity", "id": "sender-identity-id" }
    },
    "data": {
        "object": "document",
        "onBehalfOf": "sender.identity@example.com",
        "behalfOf": { "id": "sender-identity-id", "email": "sender.identity@example.com" }
    }
}

No. The context object is only populated for documents and templates created on or after January 08, 2026, and it is currently not included for these failure events: SendFailed, TemplateCreateFailed, TemplateSendFailed, EditFailed. Always check for context availability.

previousState is null when diff processing is not performed. Your handler should handle null, {} (empty object), and objects with previous values.

Newly added items have no previous values. Use previousState to detect updates/removals; compare with stored state to detect additions.

No. Date/time values are typically Unix timestamps (seconds). Convert them appropriately.

Use actor.userType first:

• Signer/Cc - Document: match with data.signerDetails[].id / data.ccDetails[].id
• SenderIdentity - Match with data.behalfOf.id
• Sender/Admin/Creator - BoldSign user IDs

The actor can be any participant type. Always use context.actor rather than inferring.

For Reminder events, context.actor identifies who triggered the reminder (typically Sender/Admin), not the recipients.

To identify which signers were reminded, use context.previousState.signerDetails[] and match by id to data.signerDetails[]. Each entry in previousState.signerDetails[] corresponds to a signer whose reminder-related fields changed (for example, lastReminderSentOn).