Event Subscriptions

An EventSubscription selects EventRecords for an EventChannel and sends them to one or more EventTargets.

List Event Subscriptions

Endpoint

GET/event_subscriptions

Return Object

EventSubscription[]

Authorization Requirement

Requires a Site-Wide API key, or a User API key or session from a Site Administrator or a Workspace Administrator for the relevant workspace.

Additional Arguments

Example Request

curl https://app.files.com/api/rest/v1/event_subscriptions.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

[
  {
    "id": 1,
    "event_channel_id": 1,
    "workspace_id": 1,
    "apply_to_all_workspaces": true,
    "name": "example",
    "subject": "example",
    "message": "example",
    "message_only": true,
    "enabled": true,
    "event_types": [
      "sync_run.failure.v1"
    ],
    "filter": {
      "payload.sync_name": {
        "prefix": "Nightly"
      },
      "payload.event_errors": {
        "exists": true
      }
    },
    "delivery_policy": "example",
    "event_target_ids": [
      1
    ],
    "created_at": "2000-01-01T01:00:00Z",
    "updated_at": "2000-01-01T01:00:00Z"
  }
]

Show Event Subscription

Endpoint

GET/event_subscriptions/{id}

Return Object

EventSubscription

Authorization Requirement

Requires a Site-Wide API key, or a User API key or session from a Site Administrator or a Workspace Administrator for the relevant workspace.

Request Parameters

ParameterDescription
id
int64
Required		Event Subscription ID.

Example Request

curl https://app.files.com/api/rest/v1/event_subscriptions/{id}.json \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "event_channel_id": 1,
  "workspace_id": 1,
  "apply_to_all_workspaces": true,
  "name": "example",
  "subject": "example",
  "message": "example",
  "message_only": true,
  "enabled": true,
  "event_types": [
    "sync_run.failure.v1"
  ],
  "filter": {
    "payload.sync_name": {
      "prefix": "Nightly"
    },
    "payload.event_errors": {
      "exists": true
    }
  },
  "delivery_policy": "example",
  "event_target_ids": [
    1
  ],
  "created_at": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z"
}

Create Event Subscription

Endpoint

POST/event_subscriptions

Return Object

EventSubscription

Authorization Requirement

Requires a Site-Wide API key, or a User API key or session from a Site Administrator or a Workspace Administrator for the relevant workspace.

Request Parameters

ParameterDefaultDescription
event_channel_id
int64		Event Channel ID
workspace_id
int64		0Workspace ID. 0 means the default workspace or site-wide.
apply_to_all_workspaces
boolean		falseIf true, this default-workspace subscription applies to events from all workspaces.
name
string
Required		Event Subscription name.
subject
string		Custom subject line to use for notification emails.
message
string		Custom message to include in notification emails.
message_only
boolean		falseIf true, notification email bodies contain only the custom message, omitting event details and the review button. Requires a custom message, defaults to false, and does not affect non-email targets.
enabled
boolean		trueWhether this Event Subscription can dispatch events.
event_types
array(string)		Event type strings matched by this subscription. Blank means all event types. Valid values: automation_run.canceled.v1, automation_run.failure.v1, automation_run.failure_will_retry.v1, automation_run.partial_failure.v1, automation_run.partial_failure_will_retry.v1, automation_run.skipped.v1, automation_run.success.v1, expectation_evaluation.invalid.v1, expectation_evaluation.late.v1, expectation_evaluation.missing.v1, expectation_evaluation.success.v1, expectation_incident.acknowledged.v1, expectation_incident.open.v1, expectation_incident.resolved.v1, expectation_incident.snoozed.v1, external_event.client_log.failure.v1, external_event.client_log.partial_failure.v1, external_event.client_log.skipped.v1, external_event.client_log.success.v1, pending_work_event.failure.v1, pending_work_event.partial_failure.v1, pending_work_event.skipped.v1, pending_work_event.success.v1, siem_http_destination_event.failure.v1, siem_http_destination_event.partial_failure.v1, siem_http_destination_event.skipped.v1, siem_http_destination_event.success.v1, sso_event.ldap_login.failure.v1, sso_event.ldap_login.partial_failure.v1, sso_event.ldap_login.skipped.v1, sso_event.ldap_login.success.v1, sso_event.ldap_sync.failure.v1, sso_event.ldap_sync.partial_failure.v1, sso_event.ldap_sync.skipped.v1, sso_event.ldap_sync.success.v1, sso_event.saml_login.failure.v1, sso_event.saml_login.partial_failure.v1, sso_event.saml_login.skipped.v1, sso_event.saml_login.success.v1, sync_run.failure.v1, sync_run.partial_failure.v1, sync_run.skipped.v1, sync_run.success.v1, user_security_event.lockout.v1
filter
object		Conditions on event fields that an event must meet to be delivered, keyed by dot-notation field path. All conditions must match.
delivery_policy
object		Event Subscription delivery policy.
event_target_ids
array(int64)		Event Target IDs this subscription sends to.

Example Request

curl https://app.files.com/api/rest/v1/event_subscriptions.json \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"event_channel_id":1,"workspace_id":1,"apply_to_all_workspaces":true,"name":"example","subject":"example","message":"example","message_only":true,"enabled":true,"event_types":["sync_run.failure.v1"],"filter":{"payload.sync_name":{"prefix":"Nightly"},"payload.event_errors":{"exists":true}},"delivery_policy":"example","event_target_ids":[1]}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "event_channel_id": 1,
  "workspace_id": 1,
  "apply_to_all_workspaces": true,
  "name": "example",
  "subject": "example",
  "message": "example",
  "message_only": true,
  "enabled": true,
  "event_types": [
    "sync_run.failure.v1"
  ],
  "filter": {
    "payload.sync_name": {
      "prefix": "Nightly"
    },
    "payload.event_errors": {
      "exists": true
    }
  },
  "delivery_policy": "example",
  "event_target_ids": [
    1
  ],
  "created_at": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z"
}

Update Event Subscription

Endpoint

PATCH/event_subscriptions/{id}

Return Object

EventSubscription

Authorization Requirement

Requires a Site-Wide API key, or a User API key or session from a Site Administrator or a Workspace Administrator for the relevant workspace.

Request Parameters

ParameterDescription
id
int64
Required		Event Subscription ID.
event_channel_id
int64		Event Channel ID
workspace_id
int64		Workspace ID. 0 means the default workspace or site-wide.
apply_to_all_workspaces
boolean		If true, this default-workspace subscription applies to events from all workspaces.
name
string		Event Subscription name.
subject
string		Custom subject line to use for notification emails.
message
string		Custom message to include in notification emails.
message_only
boolean		If true, notification email bodies contain only the custom message, omitting event details and the review button. Requires a custom message, defaults to false, and does not affect non-email targets.
enabled
boolean		Whether this Event Subscription can dispatch events.
event_types
array(string)		Event type strings matched by this subscription. Blank means all event types. Valid values: automation_run.canceled.v1, automation_run.failure.v1, automation_run.failure_will_retry.v1, automation_run.partial_failure.v1, automation_run.partial_failure_will_retry.v1, automation_run.skipped.v1, automation_run.success.v1, expectation_evaluation.invalid.v1, expectation_evaluation.late.v1, expectation_evaluation.missing.v1, expectation_evaluation.success.v1, expectation_incident.acknowledged.v1, expectation_incident.open.v1, expectation_incident.resolved.v1, expectation_incident.snoozed.v1, external_event.client_log.failure.v1, external_event.client_log.partial_failure.v1, external_event.client_log.skipped.v1, external_event.client_log.success.v1, pending_work_event.failure.v1, pending_work_event.partial_failure.v1, pending_work_event.skipped.v1, pending_work_event.success.v1, siem_http_destination_event.failure.v1, siem_http_destination_event.partial_failure.v1, siem_http_destination_event.skipped.v1, siem_http_destination_event.success.v1, sso_event.ldap_login.failure.v1, sso_event.ldap_login.partial_failure.v1, sso_event.ldap_login.skipped.v1, sso_event.ldap_login.success.v1, sso_event.ldap_sync.failure.v1, sso_event.ldap_sync.partial_failure.v1, sso_event.ldap_sync.skipped.v1, sso_event.ldap_sync.success.v1, sso_event.saml_login.failure.v1, sso_event.saml_login.partial_failure.v1, sso_event.saml_login.skipped.v1, sso_event.saml_login.success.v1, sync_run.failure.v1, sync_run.partial_failure.v1, sync_run.skipped.v1, sync_run.success.v1, user_security_event.lockout.v1
filter
object		Conditions on event fields that an event must meet to be delivered, keyed by dot-notation field path. All conditions must match.
delivery_policy
object		Event Subscription delivery policy.
event_target_ids
array(int64)		Event Target IDs this subscription sends to.

Example Request

curl https://app.files.com/api/rest/v1/event_subscriptions/{id}.json \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"event_channel_id":1,"workspace_id":1,"apply_to_all_workspaces":true,"name":"example","subject":"example","message":"example","message_only":true,"enabled":true,"event_types":["sync_run.failure.v1"],"filter":{"payload.sync_name":{"prefix":"Nightly"},"payload.event_errors":{"exists":true}},"delivery_policy":"example","event_target_ids":[1]}' \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

Example Response

{
  "id": 1,
  "event_channel_id": 1,
  "workspace_id": 1,
  "apply_to_all_workspaces": true,
  "name": "example",
  "subject": "example",
  "message": "example",
  "message_only": true,
  "enabled": true,
  "event_types": [
    "sync_run.failure.v1"
  ],
  "filter": {
    "payload.sync_name": {
      "prefix": "Nightly"
    },
    "payload.event_errors": {
      "exists": true
    }
  },
  "delivery_policy": "example",
  "event_target_ids": [
    1
  ],
  "created_at": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z"
}

Delete Event Subscription

Endpoint

DELETE/event_subscriptions/{id}

Return Object

No return value.

Authorization Requirement

Requires a Site-Wide API key, or a User API key or session from a Site Administrator or a Workspace Administrator for the relevant workspace.

Request Parameters

ParameterDescription
id
int64
Required		Event Subscription ID.

Example Request

curl https://app.files.com/api/rest/v1/event_subscriptions/{id}.json \
  -X DELETE \
  -H 'X-FilesAPI-Key: YOUR_API_KEY'

The EventSubscription Object

Some of the endpoints above return a EventSubscription object. The attributes of this object are listed below.

AttributeDescription
id
int64		Event Subscription ID
event_channel_id
int64		Event Channel ID
workspace_id
int64		Workspace ID. 0 means the default workspace or site-wide.
apply_to_all_workspaces
boolean		If true, this default-workspace subscription applies to events from all workspaces.
name
string		Event Subscription name.
subject
string		Custom subject line to use for notification emails.
message
string		Custom message to include in notification emails.
message_only
boolean		If true, notification email bodies contain only the custom message, omitting event details and the review button. Requires a custom message, defaults to false, and does not affect non-email targets.
enabled
boolean		Whether this Event Subscription can dispatch events.
event_types
array(string)		Event type strings matched by this subscription. Blank means all event types. Valid values: automation_run.canceled.v1, automation_run.failure.v1, automation_run.failure_will_retry.v1, automation_run.partial_failure.v1, automation_run.partial_failure_will_retry.v1, automation_run.skipped.v1, automation_run.success.v1, expectation_evaluation.invalid.v1, expectation_evaluation.late.v1, expectation_evaluation.missing.v1, expectation_evaluation.success.v1, expectation_incident.acknowledged.v1, expectation_incident.open.v1, expectation_incident.resolved.v1, expectation_incident.snoozed.v1, external_event.client_log.failure.v1, external_event.client_log.partial_failure.v1, external_event.client_log.skipped.v1, external_event.client_log.success.v1, pending_work_event.failure.v1, pending_work_event.partial_failure.v1, pending_work_event.skipped.v1, pending_work_event.success.v1, siem_http_destination_event.failure.v1, siem_http_destination_event.partial_failure.v1, siem_http_destination_event.skipped.v1, siem_http_destination_event.success.v1, sso_event.ldap_login.failure.v1, sso_event.ldap_login.partial_failure.v1, sso_event.ldap_login.skipped.v1, sso_event.ldap_login.success.v1, sso_event.ldap_sync.failure.v1, sso_event.ldap_sync.partial_failure.v1, sso_event.ldap_sync.skipped.v1, sso_event.ldap_sync.success.v1, sso_event.saml_login.failure.v1, sso_event.saml_login.partial_failure.v1, sso_event.saml_login.skipped.v1, sso_event.saml_login.success.v1, sync_run.failure.v1, sync_run.partial_failure.v1, sync_run.skipped.v1, sync_run.success.v1, user_security_event.lockout.v1
filter
object		Conditions on event fields that an event must meet to be delivered, keyed by dot-notation field path. All conditions must match.
delivery_policy
object		Event Subscription delivery policy.
event_target_ids
array(int64)		Event Target IDs this subscription sends to.
created_at
date-time		Event Subscription create date/time.
updated_at
date-time		Event Subscription update date/time.

Example EventSubscription Object

{
  "id": 1,
  "event_channel_id": 1,
  "workspace_id": 1,
  "apply_to_all_workspaces": true,
  "name": "example",
  "subject": "example",
  "message": "example",
  "message_only": true,
  "enabled": true,
  "event_types": [
    "sync_run.failure.v1"
  ],
  "filter": {
    "payload.sync_name": {
      "prefix": "Nightly"
    },
    "payload.event_errors": {
      "exists": true
    }
  },
  "delivery_policy": "example",
  "event_target_ids": [
    1
  ],
  "created_at": "2000-01-01T01:00:00Z",
  "updated_at": "2000-01-01T01:00:00Z"
}

filter

Each key is the full dot-notation path to a field in the event JSON that webhook targets receive, such as payload.status. Paths can reference top-level fields such as type, workspace_id, and occurred_at, actor fields such as actor.username, human-readable fields such as human.title, and event-specific fields under payload, such as payload.status, payload.sync_name, or payload.automation_name. Fields under payload vary by event type. Every segment of a path must name an object key.
Each value is the condition that field must meet: a plain value, an array of values, or an object with exactly one operator key. A plain value works the same as equals, and an array works the same as one_of.
An event matches only when every condition matches. An empty object matches every event of the subscription's event types.

Example filter

{
  "payload.sync_name": {
    "prefix": "Nightly"
  },
  "payload.event_errors": {
    "exists": true
  }
}

Filter operators