The Current webhooks model is the supported shape for all new integrations. It uses a generic object / record terminology that extends safely beyond Parties and Projects to any custom entity you define in TrustLayer.

Notifications are delivered via HTTP POST to a URL you register, carrying a JSON payload that describes the event and the records it applies to. The endpoint management API is shared with the legacy model — see Managing webhooks for how to register, list, and delete webhooks.

Request headers

Each delivery is an HTTP POST with the following headers:

Workspace administrators can configure additional custom headers (for example, Authorization: Bearer …) that are appended to every delivery. Custom headers may override User-Agent but cannot replace Content-Type or X-Hmac-Hash.

If your endpoint sits behind a WAF or bot-protection service, make sure it does not block requests based on the User-Agent value — legitimate webhook deliveries always carry one, and rules that filter unknown agents will reject them.

Terminology

TrustLayer models your data as a small set of generic entities. Each entity comes in two layers: the object (the schema) and the record (an individual instance).

Every event references at least one object / record pair, so consumers always know both what kind of thing changed and which instance it was.

Common payload shape

All current events include the following top-level fields:

{
  "workspaceId": "ID of your TrustLayer workspace",
  "eventType": "The event type identifier (see lists below)"
}

Legacy events use organizationId instead of workspaceId. The underlying value is the same — the field name changed to match the rest of the platform.

Events that reference a primary entity add:

{
  "primaryObject": { "id": "...", "name": "Party" },
  "primaryRecord": { "id": "...", "name": "Acme Construction" }
}

Events that reference a context entity add:

{
  "contextObject": { "id": "...", "name": "Project" },
  "contextRecord": { "id": "...", "name": "North Campus" }
}

Events that reference a request entity always carry the primary pair, and optionally carry the context pair:

{
  "requestObject": { "id": "...", "name": "Project-Party" },
  "requestRecord": { "id": "...", "name": "Acme @ North Campus" },
  "primaryObject": { "id": "...", "name": "Party" },
  "primaryRecord": { "id": "...", "name": "Acme Construction" },
  "contextObject": { "id": "...", "name": "Project" },
  "contextRecord": { "id": "...", "name": "North Campus" }
}

The .name field on a record is optional — it may be absent when the record has no display name yet (for example, a primary record created as a stub before enrichment).

Primary record events

Fired when a primary record is created, updated, or transitions state.

Payload:

{
  "workspaceId": "...",
  "eventType": "primary_record:created",
  "primaryObject": { "id": "...", "name": "Party" },
  "primaryRecord": { "id": "...", "name": "Acme Construction" }
}

Primary record tag events

Fired when a tag is attached to or removed from a primary record.

Payload: primary record payload plus a tag object.

{
  "workspaceId": "...",
  "eventType": "primary_record:tag:added",
  "primaryObject": { "id": "...", "name": "Party" },
  "primaryRecord": { "id": "...", "name": "Acme Construction" },
  "tag":           { "id": "...", "name": "high-risk" }
}

Primary record attribute events

Fired when a custom-field value on a primary record is set, changed, or cleared. Each individual attribute change produces one delivery — bulk edits produce one event per changed attribute.

Payload: primary record payload plus an attribute delta with the new and previous value.

{
  "workspaceId": "...",
  "eventType": "primary_record:attribute:updated",
  "primaryObject": { "id": "...", "name": "Party" },
  "primaryRecord": { "id": "...", "name": "Acme Construction" },
  "attribute": {
    "id":   "...",
    "name": "Region",
    "value":         { "value": "EMEA" },
    "previousValue": { "value": "NA"   }
  }
}

Primary record message events

Fired for conversation-level email activity tied to a primary record. Payloads are metadata only — message bodies and attachments are never delivered through webhooks.

The payload shape varies by sub-type.

primary_record:message:sent

{
  "workspaceId": "...",
  "eventType": "primary_record:message:sent",
  "primaryRecord": { "id": "...", "name": "Acme Construction" },
  "conversationId": "...",
  "conversationSubject": "Certificate of insurance renewal",
  "senderEmail": "ops@yourcompany.example",
  "senderName": "Jane Operator",
  "recipients": ["insurance@acme.example"]
}

primary_record:message:received

{
  "workspaceId": "...",
  "eventType": "primary_record:message:received",
  "primaryRecord": { "id": "...", "name": "Acme Construction" },
  "conversationId": "...",
  "conversationSubject": "Re: Certificate of insurance renewal",
  "senderEmail": "insurance@acme.example",
  "senderName": "Acme Insurance"
}

primary_record:message:failed

{
  "workspaceId": "...",
  "eventType": "primary_record:message:failed",
  "primaryRecord": { "id": "...", "name": "Acme Construction" },
  "contactEmail": "insurance@acme.example",
  "reason": "Mailbox does not exist"
}

reason is best-effort and may be omitted if the upstream provider did not report one.

Context record events

Fired when a context record (e.g. a Project) is created, updated, or transitions state.

Payload:

{
  "workspaceId": "...",
  "eventType": "context_record:created",
  "contextObject": { "id": "...", "name": "Project" },
  "contextRecord": { "id": "...", "name": "North Campus" }
}

Context record attribute events

Fired when a custom-field value on a context record is set, changed, or cleared. Each individual attribute change produces one delivery. Date-typed values are normalized to ISO 8601 strings on the wire.

Payload: context record payload plus an attribute delta with the new and previous value.

{
  "workspaceId": "...",
  "eventType": "context_record:attribute:updated",
  "contextObject": { "id": "...", "name": "Project" },
  "contextRecord": { "id": "...", "name": "North Campus" },
  "attribute": {
    "id":   "...",
    "name": "StartDate",
    "value":         { "value": "2026-01-01T00:00:00.000Z" },
    "previousValue": { "value": "2025-12-01T00:00:00.000Z" }
  }
}

The attribute object follows the same shape as in Primary record attribute events. Date-typed custom fields are delivered as ISO 8601 strings.

Request record events

Fired when the link between a primary record and an (optional) context record is created, updated, or transitions state. A request record without a context represents a global requirement on a primary record.

Payload:

{
  "workspaceId": "...",
  "eventType": "request_record:created",
  "requestObject": { "id": "...", "name": "Project-Party" },
  "requestRecord": { "id": "...", "name": "Acme @ North Campus" },
  "primaryObject": { "id": "...", "name": "Party" },
  "primaryRecord": { "id": "...", "name": "Acme Construction" },
  "contextObject": { "id": "...", "name": "Project" },
  "contextRecord": { "id": "...", "name": "North Campus" }
}

contextObject and contextRecord are omitted when the request record is not scoped to a context.

Request record attribute events

Fired when a custom-field value on a request record is set, changed, or cleared. Each individual attribute change produces one delivery — bulk edits produce one event per changed attribute.

Payload: request record payload plus an attribute delta with the new and previous value.

{
  "workspaceId": "...",
  "eventType": "request_record:attribute:updated",
  "requestObject": { "id": "...", "name": "Project-Party" },
  "requestRecord": { "id": "...", "name": "Acme @ North Campus" },
  "primaryObject": { "id": "...", "name": "Party" },
  "primaryRecord": { "id": "...", "name": "Acme Construction" },
  "contextObject": { "id": "...", "name": "Project" },
  "contextRecord": { "id": "...", "name": "North Campus" },
  "attribute": {
    "id":   "...",
    "name": "Status",
    "value":         { "optionId": "...", "value": "Approved" },
    "previousValue": { "optionId": "...", "value": "Pending"  }
  }
}

contextObject and contextRecord are omitted when the request record is not scoped to a context. The attribute object follows the same shape as in Primary record attribute events.

Primary record document events

Fired when a document is associated with a primary record. This is the v2 event for the document-to-primary-record relationship; it dispatches alongside the legacy document:assigned:to:party.

Metadata-only. Webhook payloads never carry document file contents, binary data, or storage keys. Fetch the document via the REST API using document.id.

Payload — v2 common envelope plus primaryRecord, document, and the acting user’s identity. Unlike other primary-record events, primaryObject is not included.

{
  "workspaceId": "...",
  "eventType": "document:primary_record:assigned",
  "primaryRecord": { "id": "...", "name": "Acme Construction" },
  "document":      { "id": "...", "name": "policy.pdf" },
  "userName": "Jane Operator",
  "userEmail": "jane@yourcompany.example"
}

Triggers. Fires whenever a document is attached to a primary record — through the UI, a document upload that resolves to a known primary record, or the REST API. Bulk assignments produce one webhook delivery per (document, primaryRecord) pair, not a single batched payload. Reassigning a document to a different primary record fires a new event for the new target.

Parallel legacy dispatch. Every successful document-to-primary-record assignment also fires the legacy document:assigned:to:party event. Legacy dispatch is best-effort: it is wrapped in a guard so that a legacy delivery failure cannot block the v2 event or the underlying assignment. Both events follow at-least-once delivery semantics, the same as every other webhook.

v1 → v2 field mapping

For integrations migrating from the legacy document:assigned:to:party event:

Request record compliance events

Fired when the compliance status of a request record changes. The score is always an integer from 0 to 100.

Payload: the request record payload plus compliance fields.

{
  "workspaceId": "...",
  "eventType": "request_record_compliance:reached",
  "requestObject": { "id": "...", "name": "Project-Party" },
  "requestRecord": { "id": "...", "name": "Acme @ North Campus" },
  "primaryObject": { "id": "...", "name": "Party" },
  "primaryRecord": { "id": "...", "name": "Acme Construction" },
  "contextObject": { "id": "...", "name": "Project" },
  "contextRecord": { "id": "...", "name": "North Campus" },
  "prevSubjectsComplianceScore": 80,
  "subjectsComplianceScore": 100,
  "subjectsCount": 5,
  "compliantSubjectsCount": 5
}

Full event list

Wildcards are supported when subscribing — e.g. primary_record:* matches every primary record event, including tag and message events.

Webhooks allow third-party developers to be notified whenever a specific event occurs on the TrustLayer platform. Notifications are performed via HTTP POST calls to a provided endpoint URL, carrying with them a payload with the relevant data.

You can set up webhooks either via the UI (in the Settings→TrustLayer API pane), or via API calls (with more precise control).

Request headers

Each delivery is an HTTP POST with the following headers:

Workspace administrators can configure additional custom headers (for example, Authorization: Bearer …) that are appended to every delivery. Custom headers may override User-Agent but cannot replace Content-Type or X-Hmac-Hash.

If your endpoint sits behind a WAF or bot-protection service, make sure it does not block requests based on the User-Agent value — legitimate webhook deliveries always carry one, and rules that filter unknown agents will reject them.

The payload that is sent with each webhook notification will have some common attributes:

{
  "organizationId": "The id of your organization",
  "eventType": "The type identifier of the event (see list below)"
}

Most webhooks are relative either to a party or a project (or both). In this case the payload will carry these properties:

{
  "partyId": "Id of the affected party",
  "partyName": "Name of the party",
  "projectId": "Id of the affected project",
  "projectName": "Name of the project"
}

For tag-related events, these attributes are included:

{
  "tagId": "Id of the affected tag",
  "tagName": "Name of the tag"
}

For document-related events, these attributes are supported (not all of them will be present at all times):

{
  "documentId": "Id of the affected document",
  "documentName": "Name of the document",
  "documentReviewed": "Boolean flag, true if the document was reviewed",
  "flagSeverityLevel": "Either 'low', 'medium' or 'high'",
  "flagNotes": "Text entered in the flag notes",
  "verificationNotes": "Text entered in the verification notes"
}

For document:assigned:to:party, the payload includes the acting user’s identity:

{
  "userName": "Name of the user who performed the assignment",
  "userEmail": "Email of the user who performed the assignment"
}

Both fields are empty strings for system or automated actors. Document file contents are never delivered through webhooks — fetch the document through the REST API using documentId.

Compliance-related events always carry this attribute:

{
  "complianceScore": "Numeric value representing the score of the compliance status (0-100)"
}

Currently, these events are supported:

You can create a webhook via the public API:

curl -XPOST -H"Authorization: Bearer ${token}" \
    --data '{ \
      "id": "webhook_id", \
      "namespace": "my_app", \
      "url": "https://my-app.example.com/notify", \
      "events": ["party:created", "party:updated"], \
      "enabled": true
     }' \
    https://api.trustlayer.io/v1/webhooks

• The namespace parameter can be whatever you want, but the "trustlayer" value is reserved for internal use.
• The url parameter needs to be unique relative to the namespace; if you perform a second POST request using the same values, you will overwrite the existing webhook
• The events parameter is a list of the events you’re interested in; they can also be specified using wildcards (e.g. "party:*") to express interest for a whole class of events. Finally, if you specify an empty list, your endpoint will be notified for all events.
• The enabled parameter can be omitted, and it will default to true.

Note that webhooks created via the API will not be displayed in the platform Settings page. You can list these webhooks via a GET request:

curl -XGET -H "Authorization: Bearer ${token}" https://api.trustlayer.io/v1/webhooks

You can also delete a webhook via the API:

curl -XDELETE
    -H "Authorization: Bearer ${token}" \
    https://api.trustlayer.io/v1/webhooks/webhook_id

Where webhook_id is the unique identifier of the webhook you want to delete as defined in the POST response:

{
  "id": "webhook_id",
  "namespace": "my_app",
  "url": "https://my-app.example.com/notify",
  "events": ["party:created", "party:updated"],
  "enabled": true
}