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

# Update Webhook Endpoint

> Update an existing webhook endpoint's configuration

<Note>
  This endpoint requires HMAC-SHA256 authentication. See [Authentication](../../docs/terminal-gateway/authentication) for signature computation details.
</Note>

## Partial Updates

All fields in the request body are optional. Only provide the fields you want to change.

## URL Changes

If you update the endpoint URL, the system sends a validation ping to verify the new URL is accessible. If the ping fails, the update is rejected.

## Disabling Endpoints

To temporarily stop receiving webhooks without deleting the endpoint, set the `status` field to `disabled`:

```json theme={null}
{
  "status": "disabled"
}
```

To re-enable, set it back to `active`:

```json theme={null}
{
  "status": "active"
}
```

<Tip>
  Disabling an endpoint is useful for maintenance periods or when troubleshooting issues, without losing your endpoint configuration.
</Tip>


## OpenAPI

````yaml api-reference/terminal-gateway/openapi.json PUT /v1/webhooks/endpoints/{endpointId}
openapi: 3.1.0
info:
  title: Terminal Gateway HTTP API
  version: 1.0.0
  description: >-
    HTTP API for POS-to-terminal communication. Enables payment processing
    through connected terminals.
  contact:
    name: Modulus Labs Support
    email: support@moduluslabs.io
servers:
  - url: https://your-endpoint.moduluslabs.io
    description: >-
      Your provisioned Terminal Gateway API endpoint. Contact
      support@moduluslabs.io to obtain your URL and credentials.
security:
  - hmacAuth: []
tags:
  - name: Terminals
    description: Terminal discovery and management
  - name: Payments
    description: Payment processing
  - name: Transactions
    description: Transaction status and reconciliation
  - name: Webhooks
    description: Webhook endpoint management for asynchronous payment notifications
paths:
  /v1/webhooks/endpoints/{endpointId}:
    put:
      tags:
        - Webhooks
      summary: Update Webhook Endpoint
      description: >-
        Update an existing webhook endpoint's configuration. If the URL is
        changed, a validation ping is sent to verify the new URL.
      operationId: updateWebhookEndpoint
      parameters:
        - name: endpointId
          in: path
          required: true
          description: The unique identifier of the webhook endpoint
          schema:
            type: string
          example: wh_01HQ3K4M5N6P7R8S9T0UVWXYZ
      requestBody:
        required: true
        description: Updated webhook endpoint configuration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookEndpointRequest'
            example:
              events:
                - payment.completed
                - payment.failed
              status: active
      responses:
        '200':
          description: Webhook endpoint updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
              example:
                endpointId: wh_01HQ3K4M5N6P7R8S9T0UVWXYZ
                url: https://api.yourcompany.com/webhooks/payments
                events:
                  - payment.completed
                  - payment.failed
                description: Production payment notifications
                status: active
                metadata:
                  environment: production
                createdAt: '2024-01-15T10:30:00.000Z'
                updatedAt: '2024-01-15T11:00:00.000Z'
        '400':
          $ref: '#/components/responses/WebhookBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/WebhookNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    UpdateWebhookEndpointRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: >-
            Updated HTTPS URL for webhook delivery. A validation ping is sent to
            verify the new URL.
        events:
          type: array
          items:
            type: string
            enum:
              - payment.completed
              - payment.failed
              - payment.cancelled
              - payment.timeout
          description: Updated array of event types to subscribe to.
        description:
          type: string
          description: Updated description for this endpoint.
        status:
          type: string
          enum:
            - active
            - disabled
          description: >-
            Endpoint status. Set to disabled to pause webhook delivery without
            deleting the endpoint.
        metadata:
          type: object
          description: Updated custom metadata.
          additionalProperties: true
    WebhookEndpoint:
      type: object
      required:
        - endpointId
        - url
        - events
        - status
        - createdAt
        - updatedAt
      properties:
        endpointId:
          type: string
          description: Unique identifier for the webhook endpoint.
        url:
          type: string
          format: uri
          description: The HTTPS URL where webhook payloads are delivered.
        events:
          type: array
          items:
            type: string
            enum:
              - payment.completed
              - payment.failed
              - payment.cancelled
              - payment.timeout
          description: Event types this endpoint is subscribed to.
        description:
          type: string
          description: Human-readable description for this endpoint.
        status:
          type: string
          enum:
            - active
            - disabled
          description: Endpoint status.
        metadata:
          type: object
          description: Custom key-value pairs associated with this endpoint.
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the endpoint was created.
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the last update.
    Error:
      type: object
      required:
        - error
        - timestamp
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Human-readable error message
            details:
              type: object
              description: Additional error details
              additionalProperties: true
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp
        requestId:
          type: string
          description: Request identifier for debugging
        transactionId:
          type: string
          description: Transaction ID if applicable
  responses:
    WebhookBadRequest:
      description: Invalid webhook request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            webhooksNotConfigured:
              summary: Webhooks not configured
              value:
                error:
                  code: WEBHOOKS_NOT_CONFIGURED
                  message: Webhooks feature is not enabled for your group
                timestamp: '2024-01-15T10:40:00.000Z'
            endpointLimitReached:
              summary: Endpoint limit reached
              value:
                error:
                  code: ENDPOINT_LIMIT_REACHED
                  message: Maximum of 16 webhook endpoints per group reached
                timestamp: '2024-01-15T10:40:00.000Z'
            invalidEndpointUrl:
              summary: Invalid endpoint URL
              value:
                error:
                  code: INVALID_ENDPOINT_URL
                  message: URL must use HTTPS protocol
                timestamp: '2024-01-15T10:40:00.000Z'
            endpointPingFailed:
              summary: Endpoint ping failed
              value:
                error:
                  code: ENDPOINT_PING_FAILED
                  message: >-
                    Validation ping to endpoint URL failed. Ensure the URL is
                    publicly accessible.
                timestamp: '2024-01-15T10:40:00.000Z'
            invalidEventType:
              summary: Invalid event type
              value:
                error:
                  code: INVALID_EVENT_TYPE
                  message: Unknown event type in events array
                timestamp: '2024-01-15T10:40:00.000Z'
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unauthorized:
              summary: Invalid API key
              value:
                error:
                  code: UNAUTHORIZED
                  message: Missing or invalid API key
                timestamp: '2024-01-15T10:40:00.000Z'
            invalidSignature:
              summary: Invalid signature
              value:
                error:
                  code: INVALID_SIGNATURE
                  message: HMAC signature verification failed
                timestamp: '2024-01-15T10:40:00.000Z'
            timestampExpired:
              summary: Timestamp expired
              value:
                error:
                  code: TIMESTAMP_EXPIRED
                  message: Request timestamp outside 5-minute window
                timestamp: '2024-01-15T10:40:00.000Z'
    Forbidden:
      description: Access denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: GROUP_MISMATCH
              message: Resource belongs to a different group
            timestamp: '2024-01-15T10:40:00.000Z'
    WebhookNotFound:
      description: Webhook endpoint not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: ENDPOINT_NOT_FOUND
              message: Webhook endpoint does not exist
            timestamp: '2024-01-15T10:40:00.000Z'
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: INTERNAL_ERROR
              message: Unexpected server error
            timestamp: '2024-01-15T10:40:00.000Z'
  securitySchemes:
    hmacAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        HMAC-SHA256 authentication. Requires three headers: x-api-key (your API
        key), x-timestamp (ISO 8601 timestamp), and x-signature (Base64-encoded
        HMAC-SHA256 signature). See Authentication documentation for signature
        computation.

````