---
title: "Update webhook"
method: PATCH
path: "/v0/webhooks/{id}"
tags: ["Webhooks"]
---

# Update webhook

`PATCH /v0/webhooks/{id}`

## Request

- Base URL: `https://test-api.shodai.network`
- URL: `https://test-api.shodai.network/v0/webhooks/{id}`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Updates a webhook URL, event types, filters, or status. The signing secret is not returned after creation.

## Path parameters

- `id` string, required

## Request body

- UpdateWebhookRequest
  - `url` string, uri: Replacement HTTPS endpoint URL.
  - `status` 'active' | 'disabled': Enable or disable delivery.
  - `eventTypes` string[]: Replacement subscribable event types. On update, omitted eventTypes leaves the current value unchanged; null or an empty array resets to agreement.transitioned.
  - `filters` WebhookFilters: Optional filters applied before delivery. agreementIds and templateIds apply to both agreement.transitioned and agreement.notification.triggered. inputIds, fromStates, and toStates apply to agreement.transitioned and to notification events with transition data. ruleIds apply to agreement.notification.triggered events. A filter key you supply must constrain something: an empty array, an array containing a blank or whitespace-only member, or a value with leading or trailing whitespace is rejected with 400. Values must be unique after trimming. To subscribe without any filters, send filters as null or as an empty object. Deploy transitions carry the payload value fromState: "" but are filtered with inputIds: ["__deploy"]; "" is not accepted as a filter value.
    - `agreementIds` string[]
    - `templateIds` string[]
    - `inputIds` string[]
    - `fromStates` string[]
    - `toStates` string[]
    - `ruleIds` string[]

## Response `200`

Updated webhook subscription.

- object
  - `data` WebhookSubscription, required
    - `id` string, required: Webhook subscription ID.
    - `principalId` string, required: Identifier of the authenticated Shodai account that owns this webhook.
    - `createdByApiKeyId` string, nullable, required: API key that created the webhook, for audit only.
    - `url` string, uri, required: HTTPS endpoint that receives signed webhook POSTs.
    - `status` 'active' | 'disabled', required: Webhook subscription status.
    - `eventTypes` string[], required: Subscribable event types this webhook can receive.
    - `filters` WebhookFilters, required: Optional filters applied before delivery. agreementIds and templateIds apply to both agreement.transitioned and agreement.notification.triggered. inputIds, fromStates, and toStates apply to agreement.transitioned and to notification events with transition data. ruleIds apply to agreement.notification.triggered events. A filter key you supply must constrain something: an empty array, an array containing a blank or whitespace-only member, or a value with leading or trailing whitespace is rejected with 400. Values must be unique after trimming. To subscribe without any filters, send filters as null or as an empty object. Deploy transitions carry the payload value fromState: "" but are filtered with inputIds: ["__deploy"]; "" is not accepted as a filter value.
      - `agreementIds` string[]
      - `templateIds` string[]
      - `inputIds` string[]
      - `fromStates` string[]
      - `toStates` string[]
      - `ruleIds` string[]
    - `createdAt` string, date-time, required: Webhook creation timestamp.
    - `updatedAt` string, date-time, required: Webhook update timestamp.
  - `meta` ResponseMeta, required
    - `apiVersion` string, required
    - `requestId` string, required: Correlation ID for support and debugging.

## Other responses

- `400`: Invalid webhook update.
- `401`: Missing or invalid API credential.
- `402`: The authenticated Shodai account has paid_required entitlement mode for the requested scope. Per-call x402 settlement is not implemented. Treat this as an entitlement/operator issue.
- `403`: The credential lacks the required OAuth scope, the account lacks entitlement, or the account cannot access the resource.
- `404`: Webhook subscription not found.

---

[API](https://skmtc.dev/shodai/apis/agreements-api.md) · [All operations](https://skmtc.dev/shodai/apis/agreements-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shodai/apis/agreements-api/revisions/0ac329d0e9a0?raw)