> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endstate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a webhook endpoint

> Changes the URL, event types, description or payload version. Send `status: "disabled"` to stop deliveries to the endpoint, or `status: "enabled"` to resume them, also after the health rule disabled it; re-enabling clears `fail_since` and the health rule starts fresh.



## OpenAPI

````yaml /openapi.json patch /v1/webhooks/endpoints/{endpoint_id}
openapi: 3.1.0
info:
  title: Endstate API
  version: 0.1.0
  description: Endstate developer API for chip verification and ownership workflows.
servers:
  - url: https://api2.endstate.io
    description: Production
  - url: https://api-staging.endstate.io
    description: Staging
security: []
paths:
  /v1/webhooks/endpoints/{endpoint_id}:
    patch:
      tags:
        - Webhooks
      summary: Update a webhook endpoint
      description: >-
        Changes the URL, event types, description or payload version. Send
        `status: "disabled"` to stop deliveries to the endpoint, or `status:
        "enabled"` to resume them, also after the health rule disabled it;
        re-enabling clears `fail_since` and the health rule starts fresh.
      operationId: updateWebhookEndpoint
      parameters:
        - schema:
            type: string
            format: uuid
            example: 8e1a7f50-90ab-4cde-8012-3456789abcde
          required: true
          name: endpoint_id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookEndpointRequest'
            example:
              status: enabled
      responses:
        '200':
          description: The updated endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
              example:
                id: 8e1a7f50-90ab-4cde-8012-3456789abcde
                url: https://hooks.example.com/endstate
                event_types:
                  - example.updated
                description: Production listener
                status: enabled
                disabled_reason: null
                fail_since: null
                api_version: '2026-09-01'
                created_at: '2026-09-22T12:00:00.000Z'
                updated_at: '2026-09-22T12:00:00.000Z'
        '400':
          description: >-
            The request was malformed or failed validation.


            | Error code | When |

            | --- | --- |

            | `validation.failed` | The request failed schema validation. See
            `error.details` for per-field issues. |

            | `webhook_endpoint.url_refused` | The endpoint URL must use https
            and point at a public host. |

            | `webhook_event_type.unknown` | One of the event types is not a
            supported webhook event. |
          x-error-codes:
            - validation.failed
            - webhook_endpoint.url_refused
            - webhook_event_type.unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation.failed:
                  summary: >-
                    The request failed schema validation. See `error.details`
                    for per-field issues.
                  value:
                    error:
                      code: validation.failed
                      message: >-
                        The request failed schema validation. See
                        `error.details` for per-field issues.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/validation-failed
                webhook_endpoint.url_refused:
                  summary: The endpoint URL must use https and point at a public host.
                  value:
                    error:
                      code: webhook_endpoint.url_refused
                      message: >-
                        The endpoint URL must use https and point at a public
                        host.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: >-
                        https://docs.endstate.io/errors/webhook-endpoint-url-refused
                webhook_event_type.unknown:
                  summary: One of the event types is not a supported webhook event.
                  value:
                    error:
                      code: webhook_event_type.unknown
                      message: One of the event types is not a supported webhook event.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: >-
                        https://docs.endstate.io/errors/webhook-event-type-unknown
        '401':
          description: |-
            Authentication failed.

            | Error code | When |
            | --- | --- |
            | `auth.unauthorized` | Credential is missing or malformed. |
          x-error-codes:
            - auth.unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                auth.unauthorized:
                  summary: Credential is missing or malformed.
                  value:
                    error:
                      code: auth.unauthorized
                      message: Credential is missing or malformed.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/auth-unauthorized
        '403':
          description: >-
            Authenticated, but not permitted.


            | Error code | When |

            | --- | --- |

            | `auth.forbidden` | Credential is valid but does not have access to
            the requested resource or action. |
          x-error-codes:
            - auth.forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                auth.forbidden:
                  summary: >-
                    Credential is valid but does not have access to the
                    requested resource or action.
                  value:
                    error:
                      code: auth.forbidden
                      message: >-
                        Credential is valid but does not have access to the
                        requested resource or action.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/auth-forbidden
        '404':
          description: >-
            The resource does not exist within your organization.


            | Error code | When |

            | --- | --- |

            | `webhook_endpoint.not_found` | The webhook endpoint does not exist
            in your organization. |
          x-error-codes:
            - webhook_endpoint.not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                webhook_endpoint.not_found:
                  summary: The webhook endpoint does not exist in your organization.
                  value:
                    error:
                      code: webhook_endpoint.not_found
                      message: >-
                        The webhook endpoint does not exist in your
                        organization.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: >-
                        https://docs.endstate.io/errors/webhook-endpoint-not-found
        '410':
          description: >-
            The resource is gone: a consumed credential or a deleted endpoint.
            See the error code.


            | Error code | When |

            | --- | --- |

            | `webhook_endpoint.deleted` | The webhook endpoint was deleted and
            cannot be used for this operation. |
          x-error-codes:
            - webhook_endpoint.deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                webhook_endpoint.deleted:
                  summary: >-
                    The webhook endpoint was deleted and cannot be used for this
                    operation.
                  value:
                    error:
                      code: webhook_endpoint.deleted
                      message: >-
                        The webhook endpoint was deleted and cannot be used for
                        this operation.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/webhook-endpoint-deleted
        '500':
          description: >-
            Something went wrong on our end.


            | Error code | When |

            | --- | --- |

            | `internal.error` | An unexpected server error occurred. Retry with
            exponential backoff and include `request_id` in any support request.
            |
          x-error-codes:
            - internal.error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal.error:
                  summary: >-
                    An unexpected server error occurred. Retry with exponential
                    backoff and include `request_id` in any support request.
                  value:
                    error:
                      code: internal.error
                      message: >-
                        An unexpected server error occurred. Retry with
                        exponential backoff and include `request_id` in any
                        support request.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/internal-error
      security:
        - ApiKeyBearer: []
components:
  schemas:
    UpdateWebhookEndpointRequest:
      type: object
      properties:
        url:
          type: string
          maxLength: 2048
          format: uri
          description: HTTPS URL on a public host.
          example: https://hooks.example.com/endstate
        event_types:
          type: array
          items:
            type: string
            minLength: 1
          minItems: 1
          maxItems: 64
          example:
            - example.updated
        description:
          type:
            - string
            - 'null'
          maxLength: 512
        api_version:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: >-
            Dated payload version; must be the current version or an older one
            the platform still renders.
          example: '2026-09-01'
        status:
          type: string
          enum:
            - enabled
            - disabled
          description: >-
            Send `disabled` to stop deliveries to the endpoint, or `enabled` to
            resume them; `recover` then resends what was missed.
    WebhookEndpoint:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 8e1a7f50-90ab-4cde-8012-3456789abcde
        url:
          type: string
          format: uri
          description: HTTPS URL that receives deliveries.
          example: https://hooks.example.com/endstate
        event_types:
          type: array
          items:
            type: string
          description: Event types this endpoint is subscribed to.
          example:
            - example.updated
        description:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - enabled
            - disabled
          description: >-
            `disabled` on the first failed delivery after `fail_since` is five
            days old, after a 410 response, or when deleted. Re-enable with
            PATCH.
          example: enabled
        disabled_reason:
          type:
            - string
            - 'null'
        fail_since:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the current run of failed deliveries began, or null while
            deliveries succeed. The next failed delivery after this is five days
            old disables the endpoint, so fix the receiver before then.
          example: null
        api_version:
          type: string
          description: Dated payload version this endpoint receives.
          example: '2026-09-01'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - url
        - event_types
        - description
        - status
        - disabled_reason
        - fail_since
        - api_version
        - created_at
        - updated_at
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              anyOf:
                - $ref: '#/components/schemas/ErrorCode'
                - type: string
              description: >-
                Stable, namespaced error code. The `ErrorCode` catalogue lists
                every code defined today; handle an unrecognized value as a
                generic failure rather than throwing, since codes are added over
                time.
              example: chip.not_found
            message:
              type: string
              description: >-
                Human-readable description, for logs and debugging. Wording may
                change without notice - never parse or match against it.
              example: Chip not found
            request_id:
              type: string
              description: >-
                Identifier for this request, matching the `X-Request-Id`
                response header. Log it and include it in any support request.
              example: req_8e1a7f50-90ab-4cde-f012-3456789abcde
            doc_url:
              type: string
              description: Documentation page for this error code.
              example: https://docs.endstate.io/errors/chip-not-found
            details:
              $ref: '#/components/schemas/ValidationErrorDetails'
          required:
            - code
            - message
            - request_id
            - doc_url
      required:
        - error
      description: >-
        Every error response, regardless of endpoint or HTTP status, uses this
        envelope.
    ErrorCode:
      type: string
      enum:
        - environment.conflict
        - environment.invalid_configuration
        - organization.changed
        - validation.failed
        - auth.unauthorized
        - auth.forbidden
        - session_token.invalid_or_expired
        - session_token.wrong_chip
        - wallet_session.invalid_or_expired
        - not_found.resource
        - rate_limit.exceeded
        - chip.not_found
        - chip.invalid_e_value
        - chip.already_scanned
        - quota.exceeded
        - chip.not_a_test_chip
        - unit.not_found
        - unit.already_exists
        - unit.not_minted
        - collection.not_found
        - collection.already_exists
        - collection.not_active
        - collection_backfill.blocked
        - organization.not_found
        - chip.already_paired
        - chip.key_unusable
        - chip.mac_required
        - chip.bulk_mixed_collections
        - chip.bulk_pending
        - unit.issuance_pending
        - claim.owner_unknown
        - claim.already_to_recipient
        - claim.in_progress
        - claim.not_found
        - chip_replacement.locked
        - chip_replacement.in_progress
        - chip_replacement.not_found
        - transfer.owner_unknown
        - transfer.already_to_recipient
        - transfer.in_progress
        - transfer.not_found
        - submission.not_executable
        - vault.not_found
        - vault.already_exists
        - vault.provisioning_failed
        - vault.not_permitted
        - vault.unavailable
        - vault.challenge_invalid
        - vault.address_in_use
        - vault.key_conflict
        - vault.signer_unauthorized
        - vault_connection.not_found
        - vault_connection.not_active
        - vault_connection.already_exists
        - vault_connection.conflict
        - idempotency.key_conflict
        - idempotency.in_progress
        - internal.error
        - webhook_endpoint.not_found
        - webhook_endpoint.deleted
        - webhook_endpoint.limit_reached
        - webhook_endpoint.url_refused
        - webhook_endpoint.signing_unavailable
        - webhook_event_type.unknown
        - webhook_event.not_found
        - webhook_endpoint.disabled
        - webhook_delivery.in_progress
        - webhook_endpoint.not_subscribed
      description: >-
        Stable, namespaced error code in `<resource>.<reason>` form. Branch on
        this rather than on `message` or the HTTP status. This is the catalogue
        as of this spec revision, not a closed set - see
        `ErrorResponse.error.code`.
      example: chip.not_found
    ValidationErrorDetails:
      type: object
      properties:
        formErrors:
          type: array
          items:
            type: string
          description: Issues that apply to the request as a whole rather than one field.
          example: []
        fieldErrors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Validation issues keyed by the field that failed.
          example:
            name:
              - Required
      required:
        - formErrors
        - fieldErrors
      description: Per-field validation detail. Present only on `validation.failed`.
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: end_sk
      description: >-
        Use `Authorization: Bearer end_sk_*` for partner API keys (e.g.
        `end_sk_AbCd_example_api_key`).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.