# Update the alert config for a catalog

Launch stage: Beta

`PATCH /api/2.0/lakewatch/{name=catalogs/*/alertConfig}`

Updates the alert delivery configuration for a catalog.

API scopes: lakewatch

## Path parameters

- `name` (string, required, ID, Immutable)

## Query parameters

- `update_mask` (string, required)
- `etag` (string, optional)
  Optimistic-concurrency precondition: if set and it does not match the
   resource's current `etag`, the update is rejected as a conflict (HTTP 409).

## Request body

- `default_security_alert_collation_window` (string, optional)
  Window for collating Signals into security alerts. Duration
   string — compact day/hour/minute/second components, e.g. `1d`, `12h`
   (see `Schedule.at_least_every` in common.proto for the grammar). Reads
   return the value as supplied. When unset or empty, the window is `1h`; the window in
   effect is reported in `effective_default_security_alert_collation_window`.
- `default_system_alert_collation_window` (string, optional)
  Window for collating SystemEvents into system alerts. Duration
   string — compact day/hour/minute/second components, e.g. `1d`, `12h`
   (see `Schedule.at_least_every` in common.proto for the grammar). Reads
   return the value as supplied. When unset or empty, the window is `1d`; the window in
   effect is reported in `effective_default_system_alert_collation_window`.
- `security_alert_export_config` (object, optional)
  Export destination for security alerts. When unset, export is off and reads
   return `{"enabled": false}`.
  - `enabled` (boolean, optional)
    Whether export is currently active.
  - `webhook` (object, optional)
    - `url` (string, optional)
      Webhook destination the server POSTs payloads to, in plaintext. Userinfo
       (`user:password@`) is sent as HTTP Basic auth.
    - `export_updates` (boolean, optional)
      Whether a later change to an already-exported alert is delivered too, as a second
       `lakewatch.alert.updated` event to the same webhook URL (a close is such an update, carrying a
       terminal `alert_state`). Creation export is unaffected either way.
      
       Opt-in, and unset means off: a webhook is an event transport rather than a system whose record
       is edited in place, so an update is an extra event the receiving consumer has to correlate to
       the alert it already handled. A destination configured before this event existed must not start
       receiving more without its owner asking.
  - `jira` (object, optional)
    - `instance_url` (string, required)
      Jira instance URL (e.g. `https://acme.atlassian.net`).
    - `project_key` (string, required)
      Jira project key the exported issues are created under.
    - `user_email` (string, required)
      User email paired with the API token for Jira Cloud basic auth.
    - `default_issue_type` (string, required)
      Default issue type for created tickets (e.g. `Task`, `Incident`). Jira issue creation
       requires an issue type, so it is validated at config-save time rather than failing the
       export at Jira later.
    - `api_token_uc_secret` (string, required)
      Three-level Unity Catalog name (`catalog.schema.secret`) of the secret holding
       the Jira API token, paired with `user_email` as the Jira Cloud basic-auth
       credential (`email:token`). Only the name is stored; the token is read when an
       alert is exported, so rotating the secret takes effect without editing this config.
  - `slack` (object, optional)
    - `channel` (string, required)
      Channel the alert is posted to: a channel ID (e.g. `C0123456789`) or a channel
       name without the leading `#` (e.g. `soc-alerts`). The value is stored as sent, so
       a leading `#`, surrounding whitespace, or a value naming more than one channel is
       rejected. For private channels, prefer the channel ID — Slack does not guarantee
       name resolution for those.
      
       The Slack app must be a member of the channel and hold the `chat:write` scope.
    - `bot_token_uc_secret` (string, required)
      Three-level Unity Catalog name (`catalog.schema.secret`) of the secret holding
       the Slack bot token. Only the name is stored; the token is read when an alert is
       exported, so rotating the secret takes effect without editing this config.
  - `tines` (object, optional)
    - `webhook_uri` (string, required)
      Tines webhook action URL, typically of the form
       `https://<tenant>.tines.com/webhook/<path>`. Any HTTPS host is accepted, so
       that a Tines tenant on a custom domain works.
      
       The secret is sent as a header, so it must not be embedded in the URL: a
       trailing secret path segment (`/webhook/<path>/<secret>`) and a `secret`
       query parameter are both rejected. API-path-prefix URLs (`/api/public/...`)
       are not supported.
    - `webhook_secret_uc_secret` (string, required)
      Three-level Unity Catalog name (`catalog.schema.secret`) of the secret holding the Tines
       webhook secret. Only the name is stored; the secret is read when an alert is exported, so
       rotating it takes effect without editing this config. Required: without it the destination
       would be an unauthenticated endpoint.
    - `export_updates` (boolean, optional)
      Whether a later change to an already-exported alert is delivered too, as a second
       `lakewatch.alert.updated` event to the same webhook action (a close is such an update,
       carrying a terminal `alert_state`). Creation export is unaffected either way.
      
       Opt-in, and unset means off: Tines is an event transport rather than a system whose record is
       edited in place, so an update is an extra event the receiving story has to correlate to the
       alert it already handled. A destination configured before this event existed must not start
       receiving more without its owner asking.
  - `service_now` (object, optional)
    - `instance_id` (string, required)
      ServiceNow instance ID — the host label only, not the full URL. For an
       instance reachable at `https://acme.service-now.com`, this is `acme`.
    - `client_id` (string, required)
      OAuth client ID of the registered ServiceNow application. An identifier rather
       than secret material — ServiceNow shows it on the application record — so it
       is stored and read back verbatim.
    - `client_secret_uc_secret` (string, required)
      Three-level Unity Catalog name (`catalog.schema.secret`) of the secret holding
       the OAuth client secret. Only the name is stored; the secret is read when an alert
       is exported, so rotating it takes effect without editing this config.
  - `workspace_id` (string, optional)
    Deprecated and ignored: exports always egress through the request's own
     workspace. Kept so configs stored by older builds still round-trip.
- `system_alert_export_config` (object, optional)
  Export destination for system alerts. When unset, export is off and reads
   return `{"enabled": false}`.
  - `enabled` (boolean, optional)
    Whether export is currently active.
  - `webhook` (object, optional)
    - `url` (string, optional)
      Webhook destination the server POSTs payloads to, in plaintext. Userinfo
       (`user:password@`) is sent as HTTP Basic auth.
    - `export_updates` (boolean, optional)
      Whether a later change to an already-exported alert is delivered too, as a second
       `lakewatch.alert.updated` event to the same webhook URL (a close is such an update, carrying a
       terminal `alert_state`). Creation export is unaffected either way.
      
       Opt-in, and unset means off: a webhook is an event transport rather than a system whose record
       is edited in place, so an update is an extra event the receiving consumer has to correlate to
       the alert it already handled. A destination configured before this event existed must not start
       receiving more without its owner asking.
  - `jira` (object, optional)
    - `instance_url` (string, required)
      Jira instance URL (e.g. `https://acme.atlassian.net`).
    - `project_key` (string, required)
      Jira project key the exported issues are created under.
    - `user_email` (string, required)
      User email paired with the API token for Jira Cloud basic auth.
    - `default_issue_type` (string, required)
      Default issue type for created tickets (e.g. `Task`, `Incident`). Jira issue creation
       requires an issue type, so it is validated at config-save time rather than failing the
       export at Jira later.
    - `api_token_uc_secret` (string, required)
      Three-level Unity Catalog name (`catalog.schema.secret`) of the secret holding
       the Jira API token, paired with `user_email` as the Jira Cloud basic-auth
       credential (`email:token`). Only the name is stored; the token is read when an
       alert is exported, so rotating the secret takes effect without editing this config.
  - `slack` (object, optional)
    - `channel` (string, required)
      Channel the alert is posted to: a channel ID (e.g. `C0123456789`) or a channel
       name without the leading `#` (e.g. `soc-alerts`). The value is stored as sent, so
       a leading `#`, surrounding whitespace, or a value naming more than one channel is
       rejected. For private channels, prefer the channel ID — Slack does not guarantee
       name resolution for those.
      
       The Slack app must be a member of the channel and hold the `chat:write` scope.
    - `bot_token_uc_secret` (string, required)
      Three-level Unity Catalog name (`catalog.schema.secret`) of the secret holding
       the Slack bot token. Only the name is stored; the token is read when an alert is
       exported, so rotating the secret takes effect without editing this config.
  - `tines` (object, optional)
    - `webhook_uri` (string, required)
      Tines webhook action URL, typically of the form
       `https://<tenant>.tines.com/webhook/<path>`. Any HTTPS host is accepted, so
       that a Tines tenant on a custom domain works.
      
       The secret is sent as a header, so it must not be embedded in the URL: a
       trailing secret path segment (`/webhook/<path>/<secret>`) and a `secret`
       query parameter are both rejected. API-path-prefix URLs (`/api/public/...`)
       are not supported.
    - `webhook_secret_uc_secret` (string, required)
      Three-level Unity Catalog name (`catalog.schema.secret`) of the secret holding the Tines
       webhook secret. Only the name is stored; the secret is read when an alert is exported, so
       rotating it takes effect without editing this config. Required: without it the destination
       would be an unauthenticated endpoint.
    - `export_updates` (boolean, optional)
      Whether a later change to an already-exported alert is delivered too, as a second
       `lakewatch.alert.updated` event to the same webhook action (a close is such an update,
       carrying a terminal `alert_state`). Creation export is unaffected either way.
      
       Opt-in, and unset means off: Tines is an event transport rather than a system whose record is
       edited in place, so an update is an extra event the receiving story has to correlate to the
       alert it already handled. A destination configured before this event existed must not start
       receiving more without its owner asking.
  - `service_now` (object, optional)
    - `instance_id` (string, required)
      ServiceNow instance ID — the host label only, not the full URL. For an
       instance reachable at `https://acme.service-now.com`, this is `acme`.
    - `client_id` (string, required)
      OAuth client ID of the registered ServiceNow application. An identifier rather
       than secret material — ServiceNow shows it on the application record — so it
       is stored and read back verbatim.
    - `client_secret_uc_secret` (string, required)
      Three-level Unity Catalog name (`catalog.schema.secret`) of the secret holding
       the OAuth client secret. Only the name is stored; the secret is read when an alert
       is exported, so rotating it takes effect without editing this config.
  - `workspace_id` (string, optional)
    Deprecated and ignored: exports always egress through the request's own
     workspace. Kept so configs stored by older builds still round-trip.

## Returns

Returns the AlertConfig object.

## Response

```json
{
  "name": "string",
  "version": 0,
  "update_time": "string",
  "updated_by": {
    "id": "string",
    "principal_type": "REGULAR_USER",
    "email": "string",
    "display_name": "string"
  },
  "etag": "string",
  "default_security_alert_collation_window": "string",
  "default_system_alert_collation_window": "string",
  "security_alert_export_config": {
    "enabled": true,
    "webhook": {},
    "jira": {},
    "slack": {},
    "tines": {},
    "service_now": {},
    "workspace_id": "string"
  },
  "system_alert_export_config": {
    "enabled": true,
    "webhook": {},
    "jira": {},
    "slack": {},
    "tines": {},
    "service_now": {},
    "workspace_id": "string"
  },
  "effective_default_security_alert_collation_window": "string",
  "effective_default_system_alert_collation_window": "string"
}
```