--- title: "Update webhook details" method: PUT path: "/service/webhooks/{webhookId}" tags: ["Webhooks"] --- # Update webhook details `PUT /service/webhooks/{webhookId}` Update the configuration of an existing webhook. 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`](#/operations/GET_service) endpoint. HTTP events sent by the service to a client webhook's endpoint 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. Service implementations MAY partially support event filtering and transformations. Service implementations SHALL return a 400 response code if the filtering or transformation specified in the request is not supported. Service implementations SHOULD consider the security implications of providing webhooks, and include appropriate mitigations against Server Side Request Forgery (SSRF) attacks and similar. Service implementations SHOULD take appropriate steps to authorize the modification of existing webhooks. This may take the form of RBAC, or ABAC. ## Request body - Webhookput — Register to receive updates via webhook - `url` string, required — The URL to which the service instance should make HTTP POST requests with event data - `api_key_name` string — The HTTP header name that is added to the event POST - `events` string[], required — List of event types to receive - `flow_ids` Uuid[] — Limit Flow and Flow Segment events to Flows in the given list of Flow IDs - `source_ids` Uuid[] — Limit Flow, Flow Segment and Source events to Sources in the given list of Source IDs - `flow_collected_by_ids` Uuid[] — Limit Flow and Flow Segment events to those with a Flow that is collected by a Flow Collection in the given list of Flow Collection IDs. An empty array limits events to Flows that are not collected by any Flow Collection. - `source_collected_by_ids` Uuid[] — Limit Flow, Flow Segment and Source events to those with a Source that is collected by a Source Collection in the given list of Source Collection IDs. An empty array limits events to Sources that are not collected by any Source Collection. - `accept_get_urls` string[] — 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](#/operations/GET_flows-flowId-segments) API endpoint, except that the labels are represented using a JSON array rather than a (comma separated list) string. - `accept_storage_ids` Uuid[] — List of labels of `storage_id`s 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](#/operations/GET_flows-flowId-segments) API endpoint, except that the IDs are represented using a JSON array rather than a (comma separated list) string. - `presigned` boolean — 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](#/operations/GET_flows-flowId-segments) API endpoint. - `verbose_storage` boolean — 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](#/operations/GET_flows-flowId-segments) API endpoint. - `include_object_timerange` boolean — 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](#/operations/GET_flows-flowId-segments) API endpoint. - `tags` Tags — Key is a freeform string. Value is a freeform string, or an array of freeform strings. - `id` string, required — A Universally Unique Identifier (UUID) as defined in [RFC9562](https://www.rfc-editor.org/rfc/rfc9562) - `api_key_value` string — The value that the HTTP header 'api_key_name' will be set to - `status` 'created' | 'disabled', 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. ## Response `201` Success. The webhook has been updated - Webhookget — Register to receive updates via webhook - `url` string, required — The URL to which the service instance should make HTTP POST requests with event data - `api_key_name` string — The HTTP header name that is added to the event POST - `events` string[], required — List of event types to receive - `flow_ids` Uuid[] — Limit Flow and Flow Segment events to Flows in the given list of Flow IDs - `source_ids` Uuid[] — Limit Flow, Flow Segment and Source events to Sources in the given list of Source IDs - `flow_collected_by_ids` Uuid[] — Limit Flow and Flow Segment events to those with a Flow that is collected by a Flow Collection in the given list of Flow Collection IDs. An empty array limits events to Flows that are not collected by any Flow Collection. - `source_collected_by_ids` Uuid[] — Limit Flow, Flow Segment and Source events to those with a Source that is collected by a Source Collection in the given list of Source Collection IDs. An empty array limits events to Sources that are not collected by any Source Collection. - `accept_get_urls` string[] — 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](#/operations/GET_flows-flowId-segments) API endpoint, except that the labels are represented using a JSON array rather than a (comma separated list) string. - `accept_storage_ids` Uuid[] — List of labels of `storage_id`s 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](#/operations/GET_flows-flowId-segments) API endpoint, except that the IDs are represented using a JSON array rather than a (comma separated list) string. - `presigned` boolean — 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](#/operations/GET_flows-flowId-segments) API endpoint. - `verbose_storage` boolean — 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](#/operations/GET_flows-flowId-segments) API endpoint. - `include_object_timerange` boolean — 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](#/operations/GET_flows-flowId-segments) API endpoint. - `tags` Tags — Key is a freeform string. Value is a freeform string, or an array of freeform strings. - `id` string, required — A Universally Unique Identifier (UUID) as defined in [RFC9562](https://www.rfc-editor.org/rfc/rfc9562) - `error` Error — Provides more information for an error status. - `type` string, required — The error type name. - `summary` string, required — Summary description of the error and causes. - `traceback` string[] — Stack trace leading to error (as a list of strings) - `time` string, date-time, required — Time at which the error ocurred, to aid in log correlation - `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. ## Other responses - `400` — Bad request. Invalid parameters or unsupported event filtering or transformation. - `403` — Forbidden. You do not have permission to modify this resource. - `404` — The requested Webhook ID in the path is invalid, or Webhooks are not supported by this service implementation ## Changes - **2026-07-03** `3b6c8b10d051` — 2 info - added the new optional request property `allOf[subschema #1: Webhook Details]/allOf[subschema #1: Register Webhook]/include_object_timerange` - added the optional property `allOf[subschema #1: Webhook Details]/allOf[subschema #1: Register Webhook]/include_object_timerange` to the response with the `201` status - **2025-10-15** `552be51d35bd` — 1 breaking, 1 info - removed 'propertyNames' constraint from the `allOf[subschema #1: Webhook Details]/allOf[subschema #1: Register Webhook]/tags` response property for the status `201` - removed 'propertyNames' constraint from the request property `allOf[subschema #1: Webhook Details]/allOf[subschema #1: Register Webhook]/tags` - **2025-10-15** `8639ecff0b6c` — 2 info - added the new optional request property `allOf[subschema #1: Webhook Details]/allOf[subschema #1: Register Webhook]/tags` - added the optional property `allOf[subschema #1: Webhook Details]/allOf[subschema #1: Register Webhook]/tags` to the response with the `201` status - **2025-10-06** `0eeba8c316ce` — 1 info - endpoint added - **2025-04-24** `b01aaf8cffe2` — 1 breaking - api path removed without deprecation [Change history](https://skmtc.dev/aws-samples/apis/time-addressable-media-store/changes/service/webhooks/:webhookId/put.md) --- [API](https://skmtc.dev/aws-samples/apis/time-addressable-media-store.md) · [All operations](https://skmtc.dev/aws-samples/apis/time-addressable-media-store/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/aws-samples/time-addressable-media-store/revisions/eb3977b33601/schema)