Action Notification Exports

An ActionNotificationExport is an operation that provides access to outgoing webhook logs. Querying webhook logs is a little different than other APIs.

All queries against the archive must be submitted as Exports. (Even our Web UI creates an Export behind the scenes.)

In any query field in this API, you may specify multiple values separated by commas. That means that commas cannot be searched for themselves, and neither can single quotation marks.

Use the following steps to complete an export:

Initiate the export by using the Create Action Notification Export endpoint. Non Site Admins must query by folder or path.
Using the id from the response to step 1, poll the Show Action Notification Export endpoint. Check the status field until it is ready.
You can download the results of the export as a CSV file using the results_url field in the response from step 2. If you want to page through the records in JSON format, use the List Action Notification Export Results endpoint, passing the id that you got in step 1 as the action_notification_export_id parameter. Check the X-Files-Cursor-Next header to see if there are more records available, and resubmit the same request with a cursor parameter to fetch the next page of results. Unlike most API Endpoints, this endpoint does not provide X-Files-Cursor-Prev cursors allowing reverse pagination through the results. This is due to limitations in Amazon Athena, the underlying data lake for these records.

If you intend to use this API for high volume or automated use, please contact us with more information about your use case.

Example Queries

History for a folder: { "query_folder": "path/to/folder" }
History for a range of time: { "start_at": "2021-03-18 12:00:00", "end_at": "2021-03-19 12:00:00" }
History of all notifications that used GET or POST: { "query_request_method": "GET,POST" }

Show Action Notification Export

SDK Method

Files::ActionNotificationExport.find

Return Object

ActionNotificationExport

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Folder Admin permissions.

Method Arguments

Argument	Description
id int64 Required	Action Notification Export ID.

Example Request

begin
  action_notification_export = Files::ActionNotificationExport.find(id)
  # Operate on action_notification_export
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

Create Action Notification Export

SDK Method

Files::ActionNotificationExport.create

Return Object

ActionNotificationExport

Authorization Requirement

Requires either a Site-Wide API key or User API key or session from a User with Folder Admin permissions.

Method Arguments

Argument	Description
user_id int64	User ID. Provide a value of `0` to operate the current session's user.
start_at string	Start date/time of export range.
end_at string	End date/time of export range.
query_message string	Error message associated with the request, if any.
query_request_method string	The HTTP request method used by the webhook.
query_request_url string	The target webhook URL.
query_status string	The HTTP status returned from the server in response to the webhook request.
query_success boolean	true if the webhook request succeeded (i.e. returned a 200 or 204 response status). false otherwise.
query_path string	Return notifications that were triggered by actions on this specific path.
query_folder string	Return notifications that were triggered by actions in this folder.

Example Request

begin
  action_notification_export = Files::ActionNotificationExport.create(
    user_id: 1
  )
  # Operate on action_notification_export
rescue Files::NotAuthenticatedError => e
  puts "Authentication Error Occurred (#{e.class.to_s}): " + e.message
rescue Files::Error => e
  puts "Unknown Error Occurred (#{e.class.to_s}): " + e.message
end

The ActionNotificationExport Object

Some of the methods above return a ActionNotificationExport object. The attributes of this object are listed below.

Attribute	Description
id int64	History Export ID
export_version string	Version of the underlying records for the export.
start_at date-time	Start date/time of export range.
end_at date-time	End date/time of export range.
status string	Status of export. Valid values: `building`, `ready`, or `failed`
query_path string	Return notifications that were triggered by actions on this specific path.
query_folder string	Return notifications that were triggered by actions in this folder.
query_message string	Error message associated with the request, if any.
query_request_method string	The HTTP request method used by the webhook.
query_request_url string	The target webhook URL.
query_status string	The HTTP status returned from the server in response to the webhook request.
query_success boolean	true if the webhook request succeeded (i.e. returned a 200 or 204 response status). false otherwise.
results_url string	If `status` is `ready`, this will be a URL where all the results can be downloaded at once as a CSV.