Sign in

v1

latestOpenAPI 3.1.0Apache 2.02026-07-178042197.1 KB
Webhooks

Register webhook details

Register to receive event notifications as webhooks on a specified URL. Webhook messages will conform to the format in the webhooks section of the API docs, depending on the event type (as defined in the same section). Availability of this endpoint is indicated by the name "webhooks" appearing in the event_stream_mechanisms list on the service endpoint.

HTTP requests from the service SHOULD include a api_key_name header with the 'api_key_value' value. Clients SHOULD verify this against the value they provided when registering the webhook.

API implementations MAY partially support event filtering and transformations. API implementations SHALL return a 400 response code if the filtering or transformation specified in the request is not supported.

API implementations SHOULD consider the security implementations of providing webhooks, and include appropriate mitigations against Server Side Request Forgery (SSRF) attacks and similar. API implementations SHOULD take appropriate steps to authorize the modification of existing webhooks. This may take the form of RBAC, or ABAC.

post/service/webhooks

Request body

urlstring required

The URL to which the service instance should make HTTP POST requests with event data

api_key_namestring

The HTTP header name that is added to the event POST

eventsstring[] required

List of event types to receive

flow_idsUuid[]

Limit Flow and Flow Segment events to Flows in the given list of Flow IDs

source_idsUuid[]

Limit Flow, Flow Segment and Source events to Sources in the given list of Source IDs

flow_collected_by_idsUuid[]

Limit Flow and Flow Segment events to those with Flow that is collected by a Flow Collection in the given list of Flow Collection IDs

source_collected_by_idsUuid[]

Limit Flow, Flow Segment and Source events to those with Source that is collected by a Source Collection in the given list of Source Collection IDs

accept_get_urlsstring[]

List of labels of URLs to include in the get_urls property in flows/segments_added events. Where multiple get_urls filter query parameters are provided, the included get_urls will match all filters. This option is the same as the accept_get_urls query parameter for the /flows/{flowId}/segments API endpoint, except that the labels are represented using a JSON array rather than a (comma separated list) string.

accept_storage_idsUuid[]

List of labels of storage_ids to include in the get_urls property in flows/segments_added events. Where multiple get_urls filter query parameters are provided, the included get_urls will match all filters. This option is the same as the accept_storage_ids query parameter for the /flows/{flowId}/segments API endpoint, except that the IDs are represented using a JSON array rather than a (comma separated list) string.

presignedboolean

Whether to include presigned/non-presigned URLs in the get_urls property in flows/segments_added events. Where multiple get_urls filter query parameters are provided, the included get_urls will match all filters. This option is the same as the presigned query parameter for the /flows/{flowId}/segments API endpoint.

verbose_storageboolean

Whether to include storage metadata in the get_urls property in flows/segments_added events. This option is the same as the verbose_storage query parameter for the /flows/{flowId}/segments API endpoint.

include_object_timerangeboolean

If set to true, the underlying object's timerange should appear in flows/segments_added events. Assume false if omitted. This option is the same as the include_object_timerange query parameter for the /flows/{flowId}/segments API endpoint.

tagsTags

Key is a freeform string. Value is a freeform string, or an array of freeform strings.

api_key_valuestring

The value that the HTTP header 'api_key_name' will be set to

status'created' | 'disabled'

Status of the Webhook. created will register the webhook in the created state and the service instance will attempt to start sending events. disabled will register the webhook in a disabled state and will not send events. Assumed to be created if not set.

Response

Success. The webhook has been registered.

urlstring required

The URL to which the service instance should make HTTP POST requests with event data

api_key_namestring

The HTTP header name that is added to the event POST

eventsstring[] required

List of event types to receive

flow_idsUuid[]

Limit Flow and Flow Segment events to Flows in the given list of Flow IDs

source_idsUuid[]

Limit Flow, Flow Segment and Source events to Sources in the given list of Source IDs

flow_collected_by_idsUuid[]

Limit Flow and Flow Segment events to those with Flow that is collected by a Flow Collection in the given list of Flow Collection IDs

source_collected_by_idsUuid[]

Limit Flow, Flow Segment and Source events to those with Source that is collected by a Source Collection in the given list of Source Collection IDs

accept_get_urlsstring[]

List of labels of URLs to include in the get_urls property in flows/segments_added events. Where multiple get_urls filter query parameters are provided, the included get_urls will match all filters. This option is the same as the accept_get_urls query parameter for the /flows/{flowId}/segments API endpoint, except that the labels are represented using a JSON array rather than a (comma separated list) string.

accept_storage_idsUuid[]

List of labels of storage_ids to include in the get_urls property in flows/segments_added events. Where multiple get_urls filter query parameters are provided, the included get_urls will match all filters. This option is the same as the accept_storage_ids query parameter for the /flows/{flowId}/segments API endpoint, except that the IDs are represented using a JSON array rather than a (comma separated list) string.

presignedboolean

Whether to include presigned/non-presigned URLs in the get_urls property in flows/segments_added events. Where multiple get_urls filter query parameters are provided, the included get_urls will match all filters. This option is the same as the presigned query parameter for the /flows/{flowId}/segments API endpoint.

verbose_storageboolean

Whether to include storage metadata in the get_urls property in flows/segments_added events. This option is the same as the verbose_storage query parameter for the /flows/{flowId}/segments API endpoint.

include_object_timerangeboolean

If set to true, the underlying object's timerange should appear in flows/segments_added events. Assume false if omitted. This option is the same as the include_object_timerange query parameter for the /flows/{flowId}/segments API endpoint.

tagsTags

Key is a freeform string. Value is a freeform string, or an array of freeform strings.

idstring required

A Universally Unique Identifier (UUID) as defined in RFC9562

status'created' | 'started' | 'disabled' | 'error' required

Status of the Webhook. created indicates the webhook has been successfully registered but is yet to begin sending events or, depending on the service implementation, the worker responsible for sending the events has yet to start. started indicates the webhook is active and sending events. disabled indicates the webhook has been disabled by a client and is not currently sending events. error indicates an error condition has been encountered and the webhook has been disabled by the service instance. More information about the error condition will be indicated by the service instance in the error parameter. Service implementations SHOULD implement appropriate retries and only enter the error state when absolutely necesary. A webhook in the error or disabled state may be re-enabled by a client by setting the status to created. A webhook in the created or started state may be disabled by a client by setting the status to disabled. Attempting to transition an error status to disabled SHOULD be rejected.