From 4ab5853968e21e1c57884d28b8eae3c3dc373073 Mon Sep 17 00:00:00 2001 From: Jeremy Daer Date: Tue, 18 Aug 2026 17:53:42 -0700 Subject: [PATCH] Document delegated events: the performed_by person on events and webhook payloads --- sections/events.md | 29 +++++++++++++++++++++++++++++ sections/webhooks.md | 2 ++ 2 files changed, 31 insertions(+) diff --git a/sections/events.md b/sections/events.md index 9498169..27c3c60 100644 --- a/sections/events.md +++ b/sections/events.md @@ -306,6 +306,35 @@ Get events curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/recordings/2/events.json ``` +Delegated events +---------------- + +When an action was executed by an agent working on someone's behalf, the event carries an additional `performed_by` field — a person object in the same shape as `creator`, with `"personable_type": "Agent"`. The `creator` remains the person the action is attributed to; `performed_by` identifies the agent that carried it out. Events for actions performed directly omit the field. If the agent has since been deleted, historical events keep their `performed_by` person, rendered with `"personable_type": "Tombstone"` — the presence of the field itself is the durable signal that the action was performed by an agent. + +The person objects below are abbreviated to the relevant fields — both carry the full shape shown for `creator` in the example above. + +```json +{ + "id": 1052474020, + "recording_id": 1069480015, + "action": "completed", + "details": {}, + "created_at": "2026-07-21T01:06:20.752Z", + "creator": { + "id": 1049715930, + "name": "Sharon Bradford", + "personable_type": "User" + }, + "performed_by": { + "id": 1049715999, + "name": "Clawdito", + "personable_type": "Agent" + } +} +``` + +The same field appears in [webhook payloads](webhooks.md) for delegated actions. + Legacy project-scoped routes ----------------------------- diff --git a/sections/webhooks.md b/sections/webhooks.md index 663739d..4533c1d 100644 --- a/sections/webhooks.md +++ b/sections/webhooks.md @@ -103,6 +103,8 @@ All payloads follow the same JSON format: As you'll note, the recording format is the basic generic format that all other content endpoints share, with the addition of a `content` field. This format won't include as many details about the recording as other specific endpoints return. For example, for a [todo][2], this won't include fields such as `description`, `completed` or `assignees`. +When the action was executed by an agent working on the creator's behalf, the payload also includes a top-level `performed_by` field — a person object in the same shape as `creator`, with `"personable_type": "Agent"`. The `creator` remains the person the action is attributed to; `performed_by` identifies the agent that carried it out. Payloads for actions performed directly omit the field. See [Delegated events](events.md#delegated-events). + The payload for copy/move events will also include some details on the copied recording under `"copy"`. For example: ```json {