Events reference - Deck Docs

Event format

Events follow an object.action naming convention. Every event is delivered with the same envelope. The data field contains a summary of the resource at the time of the event.

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "credential.verified",
  "data": {
    "id": "cred_a1b2c3d4",
    "object": "credential",
    "status": "verified",
    "external_id": "user-12345",
    "source_id": "src_a1b2c3d4",
    "auth_method": "username_password",
    "created_at": "2025-01-15T09:28:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  },
  "created_at": "2025-01-15T09:30:00Z"
}

Field	Description
`id`	Unique event identifier with the `evt_` prefix.
`object`	Always `event`.
`type`	The event type in `object.action` format.
`data`	Summary of the resource at the time of the event. The shape depends on the resource, see the sections below.
`created_at`	When the event occurred (ISO 8601).
`request_id`	The API request that triggered the event, with the `req_` prefix. Only present when the event was caused by an API call.

Fields that have no value yet are delivered as empty strings. For example, a task run that is not part of a workflow has "workflow_id": "".

Agent events

Type	Fired when
`agent.created`	An agent is created
`agent.updated`	An agent is updated
`agent.deleted`	An agent is deleted

agent.created

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "agent.created",
  "data": {
    "id": "agt_a1b2c3d4",
    "object": "agent",
    "name": "Utility bills agent",
    "description": "Fetches utility bills and account data",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  },
  "created_at": "2025-01-15T09:30:00Z",
  "request_id": "req_a1b2c3d4"
}

agent.updated

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "agent.updated",
  "data": {
    "id": "agt_a1b2c3d4",
    "object": "agent",
    "name": "Utility bills agent",
    "description": "Fetches utility bills, statements, and account data",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-16T14:02:00Z"
  },
  "created_at": "2025-01-16T14:02:00Z",
  "request_id": "req_a1b2c3d4"
}

agent.deleted

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "agent.deleted",
  "data": {
    "id": "agt_a1b2c3d4",
    "object": "agent",
    "name": "Utility bills agent",
    "description": "Fetches utility bills, statements, and account data",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-20T11:45:00Z"
  },
  "created_at": "2025-01-20T11:45:00Z",
  "request_id": "req_a1b2c3d4"
}

Source events

Type	Fired when
`source.created`	A source is created
`source.updated`	A source is updated
`source.deleted`	A source is deleted

source.created

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "source.created",
  "data": {
    "id": "src_a1b2c3d4",
    "object": "source",
    "name": "ConEdison",
    "type": "website",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  },
  "created_at": "2025-01-15T09:30:00Z",
  "request_id": "req_a1b2c3d4"
}

source.updated

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "source.updated",
  "data": {
    "id": "src_a1b2c3d4",
    "object": "source",
    "name": "ConEdison",
    "type": "website",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-16T14:02:00Z"
  },
  "created_at": "2025-01-16T14:02:00Z",
  "request_id": "req_a1b2c3d4"
}

source.deleted

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "source.deleted",
  "data": {
    "id": "src_a1b2c3d4",
    "object": "source",
    "name": "ConEdison",
    "type": "website",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-20T11:45:00Z"
  },
  "created_at": "2025-01-20T11:45:00Z",
  "request_id": "req_a1b2c3d4"
}

Credential events

Type	Fired when
`credential.created`	A new credential is created with `unverified` status
`credential.unverified`	A previously verified credential was updated and reverted to `unverified`
`credential.verified`	Credential successfully authenticated for the first time
`credential.invalid`	Credentials were rejected by the source
`credential.deleted`	Credential was permanently removed from the vault

credential.created

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "credential.created",
  "data": {
    "id": "cred_a1b2c3d4",
    "object": "credential",
    "status": "unverified",
    "external_id": "user-12345",
    "source_id": "src_a1b2c3d4",
    "auth_method": "username_password",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  },
  "created_at": "2025-01-15T09:30:00Z",
  "request_id": "req_a1b2c3d4"
}

credential.unverified

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "credential.unverified",
  "data": {
    "id": "cred_a1b2c3d4",
    "object": "credential",
    "status": "unverified",
    "external_id": "user-12345",
    "source_id": "src_a1b2c3d4",
    "auth_method": "username_password",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-16T14:02:00Z"
  },
  "created_at": "2025-01-16T14:02:00Z",
  "request_id": "req_a1b2c3d4"
}

credential.verified

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "credential.verified",
  "data": {
    "id": "cred_a1b2c3d4",
    "object": "credential",
    "status": "verified",
    "external_id": "user-12345",
    "source_id": "src_a1b2c3d4",
    "auth_method": "username_password",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:32:00Z"
  },
  "created_at": "2025-01-15T09:32:00Z"
}

credential.invalid

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "credential.invalid",
  "data": {
    "id": "cred_a1b2c3d4",
    "object": "credential",
    "status": "invalid",
    "external_id": "user-12345",
    "source_id": "src_a1b2c3d4",
    "auth_method": "username_password",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:32:00Z"
  },
  "created_at": "2025-01-15T09:32:00Z"
}

credential.deleted

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "credential.deleted",
  "data": {
    "id": "cred_a1b2c3d4",
    "object": "credential",
    "status": "deleted",
    "external_id": "user-12345",
    "source_id": "src_a1b2c3d4",
    "auth_method": "username_password",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-20T11:45:00Z"
  },
  "created_at": "2025-01-20T11:45:00Z",
  "request_id": "req_a1b2c3d4"
}

Session events

Type	Fired when
`session.queued`	Session is waiting to be provisioned
`session.running`	Session is active and executing
`session.idle`	No active tasks, session is waiting for new work
`session.completing`	Work is done, session is shutting down
`session.completed`	Session finished and was closed
`session.failed`	Session encountered an error

session.queued

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "session.queued",
  "data": {
    "id": "sess_a1b2c3d4",
    "object": "session",
    "status": "queued",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  },
  "created_at": "2025-01-15T09:30:00Z",
  "request_id": "req_a1b2c3d4"
}

session.running

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "session.running",
  "data": {
    "id": "sess_a1b2c3d4",
    "object": "session",
    "status": "running",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:05Z"
  },
  "created_at": "2025-01-15T09:30:05Z"
}

session.idle

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "session.idle",
  "data": {
    "id": "sess_a1b2c3d4",
    "object": "session",
    "status": "idle",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:31:20Z"
  },
  "created_at": "2025-01-15T09:31:20Z"
}

session.completing

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "session.completing",
  "data": {
    "id": "sess_a1b2c3d4",
    "object": "session",
    "status": "completing",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:32:00Z"
  },
  "created_at": "2025-01-15T09:32:00Z",
  "request_id": "req_a1b2c3d4"
}

session.completed

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "session.completed",
  "data": {
    "id": "sess_a1b2c3d4",
    "object": "session",
    "status": "completed",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:32:10Z"
  },
  "created_at": "2025-01-15T09:32:10Z"
}

session.failed

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "session.failed",
  "data": {
    "id": "sess_a1b2c3d4",
    "object": "session",
    "status": "failed",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:31:40Z"
  },
  "created_at": "2025-01-15T09:31:40Z"
}

Task events

Type	Fired when
`task.created`	A task is created
`task.updated`	A task definition is updated
`task.reset`	A task is reset to `learning`, invalidating its cached plan
`task.deleted`	A task is deleted

task.created

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "task.created",
  "data": {
    "id": "task_a1b2c3d4",
    "object": "task",
    "name": "Fetch latest bill",
    "status": "learning",
    "agent_id": "agt_a1b2c3d4",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  },
  "created_at": "2025-01-15T09:30:00Z",
  "request_id": "req_a1b2c3d4"
}

task.updated

Also fired when a task graduates to a new status after successful runs, for example learning to test.

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "task.updated",
  "data": {
    "id": "task_a1b2c3d4",
    "object": "task",
    "name": "Fetch latest bill",
    "status": "test",
    "agent_id": "agt_a1b2c3d4",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-16T14:02:00Z"
  },
  "created_at": "2025-01-16T14:02:00Z"
}

task.reset

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "task.reset",
  "data": {
    "id": "task_a1b2c3d4",
    "object": "task",
    "name": "Fetch latest bill",
    "status": "learning",
    "agent_id": "agt_a1b2c3d4",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-18T10:15:00Z"
  },
  "created_at": "2025-01-18T10:15:00Z",
  "request_id": "req_a1b2c3d4"
}

task.deleted

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "task.deleted",
  "data": {
    "id": "task_a1b2c3d4",
    "object": "task",
    "name": "Fetch latest bill",
    "status": "live",
    "agent_id": "agt_a1b2c3d4",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-20T11:45:00Z"
  },
  "created_at": "2025-01-20T11:45:00Z",
  "request_id": "req_a1b2c3d4"
}

Task run events

Type	Fired when
`task_run.queued`	Run is waiting to start
`task_run.running`	Execution begins
`task_run.completed`	Run finishes successfully
`task_run.failed`	Run encounters an error
`task_run.canceling`	Cancellation requested, agent is stopping
`task_run.canceled`	Run is canceled
`task_run.interaction_required`	User input is needed during execution

Task run payloads share the same fields. result is empty until the run reaches a final result, then becomes success or failure. runtime_ms appears once the run has finished. workflow_id is empty for runs that are not part of a workflow.

task_run.queued

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "task_run.queued",
  "data": {
    "id": "trun_a1b2c3d4",
    "object": "task_run",
    "status": "queued",
    "result": "",
    "task_id": "task_a1b2c3d4",
    "workflow_id": "",
    "credential_id": "cred_a1b2c3d4",
    "session_id": "sess_a1b2c3d4",
    "agent_id": "agt_a1b2c3d4",
    "source_id": "src_a1b2c3d4",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  },
  "created_at": "2025-01-15T09:30:00Z",
  "request_id": "req_a1b2c3d4"
}

task_run.running

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "task_run.running",
  "data": {
    "id": "trun_a1b2c3d4",
    "object": "task_run",
    "status": "running",
    "result": "",
    "task_id": "task_a1b2c3d4",
    "workflow_id": "",
    "credential_id": "cred_a1b2c3d4",
    "session_id": "sess_a1b2c3d4",
    "agent_id": "agt_a1b2c3d4",
    "source_id": "src_a1b2c3d4",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:05Z"
  },
  "created_at": "2025-01-15T09:30:05Z"
}

task_run.completed

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "task_run.completed",
  "data": {
    "id": "trun_a1b2c3d4",
    "object": "task_run",
    "status": "completed",
    "result": "success",
    "task_id": "task_a1b2c3d4",
    "workflow_id": "",
    "credential_id": "cred_a1b2c3d4",
    "session_id": "sess_a1b2c3d4",
    "agent_id": "agt_a1b2c3d4",
    "source_id": "src_a1b2c3d4",
    "runtime_ms": 12453,
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:31:15Z"
  },
  "created_at": "2025-01-15T09:31:15Z"
}

task_run.failed

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "task_run.failed",
  "data": {
    "id": "trun_a1b2c3d4",
    "object": "task_run",
    "status": "failed",
    "result": "failure",
    "task_id": "task_a1b2c3d4",
    "workflow_id": "",
    "credential_id": "cred_a1b2c3d4",
    "session_id": "sess_a1b2c3d4",
    "agent_id": "agt_a1b2c3d4",
    "source_id": "src_a1b2c3d4",
    "runtime_ms": 8420,
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:55Z"
  },
  "created_at": "2025-01-15T09:30:55Z"
}

task_run.canceling

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "task_run.canceling",
  "data": {
    "id": "trun_a1b2c3d4",
    "object": "task_run",
    "status": "canceling",
    "result": "",
    "task_id": "task_a1b2c3d4",
    "workflow_id": "",
    "credential_id": "cred_a1b2c3d4",
    "session_id": "sess_a1b2c3d4",
    "agent_id": "agt_a1b2c3d4",
    "source_id": "src_a1b2c3d4",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:40Z"
  },
  "created_at": "2025-01-15T09:30:40Z",
  "request_id": "req_a1b2c3d4"
}

task_run.canceled

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "task_run.canceled",
  "data": {
    "id": "trun_a1b2c3d4",
    "object": "task_run",
    "status": "canceled",
    "result": "",
    "task_id": "task_a1b2c3d4",
    "workflow_id": "",
    "credential_id": "cred_a1b2c3d4",
    "session_id": "sess_a1b2c3d4",
    "agent_id": "agt_a1b2c3d4",
    "source_id": "src_a1b2c3d4",
    "runtime_ms": 41200,
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:45Z"
  },
  "created_at": "2025-01-15T09:30:45Z",
  "request_id": "req_a1b2c3d4"
}

task_run.interaction_required

Includes an interaction object describing the input to collect. See Handling interactions for the full interaction object reference.

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "task_run.interaction_required",
  "data": {
    "id": "trun_a1b2c3d4",
    "object": "task_run",
    "status": "interaction_required",
    "result": "",
    "task_id": "task_a1b2c3d4",
    "workflow_id": "",
    "credential_id": "cred_a1b2c3d4",
    "session_id": "sess_a1b2c3d4",
    "agent_id": "agt_a1b2c3d4",
    "source_id": "src_a1b2c3d4",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:30Z",
    "interaction": {
      "type": "mfa",
      "message": "Enter the 6-digit code sent to your phone",
      "fields": [
        {
          "name": "code",
          "type": "string",
          "label": "Verification code"
        }
      ]
    }
  },
  "created_at": "2025-01-15T09:30:30Z"
}

Storage events

Type	Fired when
`storage.created`	A file is stored during a task run

storage.created

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "storage.created",
  "data": {
    "id": "stor_a1b2c3d4",
    "object": "storage",
    "file_name": "statement-2025-01.pdf",
    "file_type": "application/pdf",
    "file_size": 245678,
    "fetch_date": "2025-01-15T09:31:10Z",
    "task_run_id": "trun_a1b2c3d4",
    "created_at": "2025-01-15T09:31:12Z"
  },
  "created_at": "2025-01-15T09:31:12Z"
}

Event destination events

Type	Fired when
`event_destination.activated`	A destination passes verification and becomes active
`event_destination.deactivated`	A destination is disabled

event_destination.activated

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "event_destination.activated",
  "data": {
    "id": "evtd_a1b2c3d4",
    "object": "event_destination",
    "name": "Production Webhook",
    "status": "active",
    "type": "webhook",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:10Z"
  },
  "created_at": "2025-01-15T09:30:10Z"
}

event_destination.deactivated

{
  "id": "evt_a1b2c3d4",
  "object": "event",
  "type": "event_destination.deactivated",
  "data": {
    "id": "evtd_a1b2c3d4",
    "object": "event_destination",
    "name": "Production Webhook",
    "status": "inactive",
    "type": "webhook",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-20T11:45:00Z"
  },
  "created_at": "2025-01-20T11:45:00Z",
  "request_id": "req_a1b2c3d4"
}

​Event format

​Agent events

​Source events

​Credential events

​Session events

​Task events

​Task run events

​Storage events

​Event destination events