Keep your backend in sync

Webhook envelope contract and representative payload examples for deployment events.

Use Webhooks to Keep Your Backend in Sync

Every webhook delivery uses this envelope:

{
  "type": "<event_name>",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {}
}

data is the delivered event payload.

The payload sections below are representative examples to guide receiver implementation. Treat the active event catalog and backend API reference as the authoritative contract surface for production validation.

user.created, user.updated, and user.deleted are emitted for both end-user self-service flows and admin-driven mutations from the backend API (POST /users, PATCH /users/{user_id}, DELETE /users/{user_id}). Subscribers should treat them identically.

User Events

user.created

{
  "type": "user.created",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "12345",
    "entity_type": "user",
    "id": "12345",
    "first_name": "Ava",
    "last_name": "Stone",
    "username": "ava",
    "profile_picture_url": "",
    "schema_version": "v1",
    "disabled": false,
    "second_factor_policy": "optional",
    "availability": "active",
    "last_password_reset_at": null,
    "active_organization_membership_id": null,
    "active_workspace_membership_id": null,
    "deployment_id": "24239923154394947",
    "public_metadata": {},
    "private_metadata": {},
    "primary_email_address_id": "4001",
    "primary_email_address": "ava@example.com",
    "primary_phone_number_id": "5001",
    "primary_phone_number": "+15551234567",
    "email_addresses": [],
    "phone_numbers": [],
    "social_connections": [],
    "segments": [],
    "has_password": true,
    "has_backup_codes": false
  }
}

user.updated

{
  "type": "user.updated",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "12345",
    "entity_type": "user",
    "id": "12345",
    "first_name": "Ava",
    "last_name": "Stone",
    "username": "ava",
    "profile_picture_url": "",
    "schema_version": "v1",
    "disabled": false,
    "second_factor_policy": "optional",
    "availability": "active",
    "last_password_reset_at": null,
    "active_organization_membership_id": null,
    "active_workspace_membership_id": null,
    "deployment_id": "24239923154394947",
    "public_metadata": {},
    "private_metadata": {},
    "primary_email_address_id": "4001",
    "primary_email_address": "ava@example.com",
    "primary_phone_number_id": "5001",
    "primary_phone_number": "+15551234567",
    "email_addresses": [],
    "phone_numbers": [],
    "social_connections": [],
    "segments": [],
    "has_password": true,
    "has_backup_codes": false
  }
}

user.deleted

{
  "type": "user.deleted",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "12345",
    "entity_type": "user",
    "id": "12345",
    "first_name": "Ava",
    "last_name": "Stone",
    "username": "ava"
  }
}

user.email.added

{
  "type": "user.email.added",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "4001",
    "entity_type": "user_email"
  }
}

user.email.removed

{
  "type": "user.email.removed",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "4001",
    "entity_type": "user_email"
  }
}

user.email.verified

{
  "type": "user.email.verified",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "4001",
    "entity_type": "user_email"
  }
}

user.phone.added

{
  "type": "user.phone.added",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "5001",
    "entity_type": "user_phone"
  }
}

user.phone.removed

{
  "type": "user.phone.removed",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "5001",
    "entity_type": "user_phone"
  }
}

user.phone.verified

{
  "type": "user.phone.verified",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "5001",
    "entity_type": "user_phone"
  }
}

user.password.updated

{
  "type": "user.password.updated",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "12345",
    "entity_type": "user"
  }
}

user.mfa.enabled

{
  "type": "user.mfa.enabled",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "12345",
    "entity_type": "user_authenticator",
    "id": "991",
    "created_at": "2026-03-04T09:59:00Z",
    "updated_at": "2026-03-04T10:00:00Z",
    "user_id": "12345",
    "otp_url": "otpauth://totp/Wacht:ava@example.com?secret=***"
  }
}

user.mfa.disabled

{
  "type": "user.mfa.disabled",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "12345",
    "entity_type": "user_authenticator",
    "id": "991",
    "created_at": "2026-03-04T09:59:00Z",
    "updated_at": "2026-03-04T10:00:00Z",
    "user_id": "12345",
    "otp_url": null
  }
}

Session Events

session.created

{
  "type": "session.created",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "7001",
    "entity_type": "session",
    "id": "7001",
    "created_at": "2026-03-04T10:00:00Z",
    "updated_at": "2026-03-04T10:00:00Z",
    "active_signin_id": "7101",
    "signins": []
  }
}

session.deleted

{
  "type": "session.deleted",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "7001",
    "entity_type": "session",
    "id": "7001",
    "created_at": "2026-03-04T10:00:00Z",
    "updated_at": "2026-03-04T10:00:00Z",
    "active_signin_id": "7101",
    "signins": []
  }
}

session.expired

{
  "type": "session.expired",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "7001",
    "entity_type": "session"
  }
}

Organization Events

organization.created

{
  "type": "organization.created",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "8001",
    "entity_type": "organization",
    "id": "8001",
    "name": "Acme Inc",
    "image_url": "",
    "description": "",
    "member_count": 1,
    "public_metadata": {},
    "private_metadata": {},
    "roles": [],
    "workspaces": [],
    "segments": []
  }
}

organization.updated

{
  "type": "organization.updated",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "8001",
    "entity_type": "organization",
    "id": "8001",
    "name": "Acme Inc"
  }
}

organization.deleted

{
  "type": "organization.deleted",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "8001",
    "entity_type": "organization"
  }
}

organization.member.added

{
  "type": "organization.member.added",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "8101",
    "entity_type": "organization_membership"
  }
}

organization.member.removed

{
  "type": "organization.member.removed",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "8101",
    "entity_type": "organization_membership"
  }
}

organization.member.role.updated

{
  "type": "organization.member.role.updated",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "8101",
    "entity_type": "organization_membership"
  }
}

organization.invitation.created

{
  "type": "organization.invitation.created",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "8201",
    "entity_type": "organization_invitation"
  }
}

organization.invitation.accepted

{
  "type": "organization.invitation.accepted",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "8201",
    "entity_type": "organization_invitation"
  }
}

organization.invitation.revoked

{
  "type": "organization.invitation.revoked",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "8201",
    "entity_type": "organization_invitation"
  }
}

Workspace Events

workspace.created

{
  "type": "workspace.created",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "9001",
    "entity_type": "workspace",
    "id": "9001",
    "name": "Production",
    "image_url": "",
    "description": "",
    "member_count": 2,
    "public_metadata": {},
    "private_metadata": {},
    "organization_id": "8001",
    "organization_name": "Acme Inc",
    "roles": [],
    "segments": []
  }
}

workspace.updated

{
  "type": "workspace.updated",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "9001",
    "entity_type": "workspace",
    "id": "9001",
    "name": "Production"
  }
}

workspace.deleted

{
  "type": "workspace.deleted",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "9001",
    "entity_type": "workspace"
  }
}

workspace.member.added

{
  "type": "workspace.member.added",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "9101",
    "entity_type": "workspace_membership"
  }
}

workspace.member.removed

{
  "type": "workspace.member.removed",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "9101",
    "entity_type": "workspace_membership"
  }
}

workspace.member.role.updated

{
  "type": "workspace.member.role.updated",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "9101",
    "entity_type": "workspace_membership"
  }
}

workspace.invitation.created

{
  "type": "workspace.invitation.created",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "9201",
    "entity_type": "workspace_invitation"
  }
}

workspace.invitation.accepted

{
  "type": "workspace.invitation.accepted",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "9201",
    "entity_type": "workspace_invitation"
  }
}

workspace.invitation.revoked

{
  "type": "workspace.invitation.revoked",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "9201",
    "entity_type": "workspace_invitation"
  }
}

API Key Events

api_key.created

{
  "type": "api_key.created",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "10001",
    "entity_type": "api_key"
  }
}

api_key.deleted

{
  "type": "api_key.deleted",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "10001",
    "entity_type": "api_key"
  }
}

api_key.rotated

{
  "type": "api_key.rotated",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "10001",
    "entity_type": "api_key"
  }
}

Agent Events

agent.created

{
  "type": "agent.created",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "11001",
    "entity_type": "agent"
  }
}

agent.updated

{
  "type": "agent.updated",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "11001",
    "entity_type": "agent"
  }
}

agent.deleted

{
  "type": "agent.deleted",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "11001",
    "entity_type": "agent"
  }
}

agent.execution.started

{
  "type": "agent.execution.started",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "11101",
    "entity_type": "agent_execution"
  }
}

agent.execution.completed

{
  "type": "agent.execution.completed",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "11101",
    "entity_type": "agent_execution"
  }
}

agent.execution.failed

{
  "type": "agent.execution.failed",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "11101",
    "entity_type": "agent_execution"
  }
}

agent.model.usage

{
  "type": "agent.model.usage",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "model": "gemini-2.5-flash",
    "is_byok": false,
    "context_id": "1234567890123456789",
    "context_group": "support",
    "input_tokens": 120,
    "cached_tokens": 0,
    "output_tokens": 32,
    "input_cost_cents": 1,
    "output_cost_cents": 1,
    "search_query_count": 0,
    "search_query_unique_count": 0,
    "search_query_cost_cents": 0,
    "total_cost_cents": 2,
    "timestamp": "2026-03-04T10:00:00Z",
    "prompt_token_count": 120,
    "candidates_token_count": 32,
    "total_token_count": 152,
    "cached_content_token_count": 0,
    "thoughts_token_count": 0
  }
}

Agent Thread Events

agent.thread.message

Emitted for every conversation message produced in an agent execution thread — user input, the agent's own steers and tool results, clarification (ask-user) questions and their answers, tool-approval requests and decisions, execution summaries, and task/coordination markers.

There is no separate webhook per subtype. They all arrive as agent.thread.message; the subtype is carried inside the payload. Switch on data.message_type (mirrored by data.content.type).

Envelope

{
  "thread_id": "1234567890123456789",
  "message_type": "conversation_message",
  "data": { /* ConversationRecord — see below */ },
  "timestamp": "2026-03-04T10:00:00Z"
}

data is the conversation record:

Field	Notes
`id`	Message id (string).
`thread_id`	Agent thread id (string).
`board_item_id`	Set when the thread runs against a task board item; otherwise omitted.
`execution_run_id`	The execution run that produced the message.
`message_type`	The subtype discriminator (table below).
`content`	Typed body; `content.type` matches `message_type`.
`timestamp` / `created_at` / `updated_at`	Timestamps.
`metadata`	Optional free-form object; omitted when absent.

data.message_type values

`message_type`	Meaning
`user_message`	Message sent into the thread by a user/caller.
`steer`	The agent's own narration / mid-run steering.
`tool_result`	Result of a tool the agent ran.
`system_decision`	Internal routing/guard decision.
`clarification_request`	Agent asked the user a question (`ask_user`). Thread moves to `waiting_for_input`.
`clarification_response`	The user's answer to a clarification request.
`approval_request`	Agent requested approval to run approval-gated tool(s). Thread moves to `waiting_for_input`.
`approval_response`	The user's allow/deny decision for an approval request.
`execution_summary`	End-of-run summary.
`task_subscription_notification`	A subscribed task changed status.
`assignment_execution_trigger` / `task_routing_trigger` / `task_handoff_received`	Multi-agent task-board coordination markers.

message_type: `user_message`

{
  "thread_id": "1234567890123456789",
  "message_type": "conversation_message",
  "data": {
    "id": "9000000000000000001",
    "thread_id": "1234567890123456789",
    "message_type": "user_message",
    "content": {
      "type": "user_message",
      "message": "Summarize last week's signups and email it to me.",
      "sender_name": "Jane Doe"
    },
    "timestamp": "2026-03-04T10:00:00Z",
    "created_at": "2026-03-04T10:00:00Z",
    "updated_at": "2026-03-04T10:00:00Z"
  },
  "timestamp": "2026-03-04T10:00:00Z"
}

message_type: `clarification_request`

The agent asked the user one or more questions via the ask_user tool. Each question's answer_kind.kind is one of free_text, single_choice, multi_choice, yes_no, number, date, confirm.

{
  "thread_id": "1234567890123456789",
  "message_type": "conversation_message",
  "data": {
    "id": "9000000000000000002",
    "thread_id": "1234567890123456789",
    "message_type": "clarification_request",
    "content": {
      "type": "clarification_request",
      "context": "I need a target before running the release.",
      "questions": [
        {
          "id": "deploy_env",
          "text": "Which environment should I deploy to?",
          "answer_kind": {
            "kind": "single_choice",
            "choices": [
              { "value": "prod", "label": "Production" },
              { "value": "staging", "label": "Staging" }
            ],
            "allow_other": false
          }
        }
      ]
    },
    "timestamp": "2026-03-04T10:00:05Z",
    "created_at": "2026-03-04T10:00:05Z",
    "updated_at": "2026-03-04T10:00:05Z"
  },
  "timestamp": "2026-03-04T10:00:05Z"
}

message_type: `clarification_response`

The user's answer. answers[].value.kind matches the question's answer_kind.kind. request_message_id points back to the clarification_request message id; freeform_text is present only when the user typed a free-form reply instead of structured answers.

{
  "thread_id": "1234567890123456789",
  "message_type": "conversation_message",
  "data": {
    "id": "9000000000000000003",
    "thread_id": "1234567890123456789",
    "message_type": "clarification_response",
    "content": {
      "type": "clarification_response",
      "request_message_id": "9000000000000000002",
      "answers": [
        { "question_id": "deploy_env", "value": { "kind": "single_choice", "value": "staging" } }
      ]
    },
    "timestamp": "2026-03-04T10:01:00Z",
    "created_at": "2026-03-04T10:01:00Z",
    "updated_at": "2026-03-04T10:01:00Z"
  },
  "timestamp": "2026-03-04T10:01:00Z"
}

message_type: `approval_request`

The agent wants to run one or more approval-gated tools and is blocked until the user responds. The thread moves to waiting_for_input.

{
  "thread_id": "1234567890123456789",
  "message_type": "conversation_message",
  "data": {
    "id": "9000000000000000004",
    "thread_id": "1234567890123456789",
    "message_type": "approval_request",
    "content": {
      "type": "approval_request",
      "description": "Approval required to run: send_email.",
      "tools": [
        {
          "tool_id": "5500000000000000001",
          "tool_name": "send_email",
          "tool_description": "Send an email to a recipient"
        }
      ]
    },
    "timestamp": "2026-03-04T10:02:00Z",
    "created_at": "2026-03-04T10:02:00Z",
    "updated_at": "2026-03-04T10:02:00Z"
  },
  "timestamp": "2026-03-04T10:02:00Z"
}

message_type: `approval_response`

The user's decision. Each approvals[].mode is allow_once or allow_always. request_message_id points back to the approval_request message id. A denial is represented by the absence of an entry for that tool.

{
  "thread_id": "1234567890123456789",
  "message_type": "conversation_message",
  "data": {
    "id": "9000000000000000005",
    "thread_id": "1234567890123456789",
    "message_type": "approval_response",
    "content": {
      "type": "approval_response",
      "request_message_id": "9000000000000000004",
      "approvals": [
        { "tool_name": "send_email", "mode": "allow_once" }
      ]
    },
    "timestamp": "2026-03-04T10:02:30Z",
    "created_at": "2026-03-04T10:02:30Z",
    "updated_at": "2026-03-04T10:02:30Z"
  },
  "timestamp": "2026-03-04T10:02:30Z"
}

message_type: `tool_result`

{
  "thread_id": "1234567890123456789",
  "message_type": "conversation_message",
  "data": {
    "id": "9000000000000000006",
    "thread_id": "1234567890123456789",
    "message_type": "tool_result",
    "content": {
      "type": "tool_result",
      "tool_name": "send_email",
      "status": "success",
      "input": { "to": "jane@example.com", "subject": "Weekly signups" },
      "output": { "message_id": "msg_abc123" }
    },
    "timestamp": "2026-03-04T10:03:00Z",
    "created_at": "2026-03-04T10:03:00Z",
    "updated_at": "2026-03-04T10:03:00Z"
  },
  "timestamp": "2026-03-04T10:03:00Z"
}

Remaining subtypes (steer, system_decision, execution_summary, task_subscription_notification, assignment_execution_trigger, task_routing_trigger, task_handoff_received) follow the same envelope: data.message_type plus a data.content object whose type matches.

agent.thread.platform_event

Emitted for platform events raised during an agent execution thread (e.g. conversation_compacted or a platform-event tool's configured label).

{
  "thread_id": "1234567890123456789",
  "message_type": "platform_event",
  "data": {
    "event_label": "conversation_compacted",
    "event_data": {}
  },
  "timestamp": "2026-03-04T10:00:00Z"
}

Waitlist Events

waitlist.entry.created

{
  "type": "waitlist.entry.created",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "12001",
    "entity_type": "waitlist_entry"
  }
}

waitlist.entry.approved

{
  "type": "waitlist.entry.approved",
  "timestamp": "2026-03-04T10:00:00.000Z",
  "data": {
    "entity_id": "12001",
    "entity_type": "waitlist_entry"
  }
}

Keep your backend in sync

On this page