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

# Create Webhook Endpoint

> Create a webhook endpoint for the current merchant. The endpoint URL must use HTTPS and resolve to a public host.



## OpenAPI

````yaml POST /webhook/endpoints
openapi: 3.1.0
info:
  title: Clink API
  description: >-
    Official API documentation for Clink's payment processing platform. This API
    enables merchants to create and manage payment sessions, handle
    subscriptions, and process transactions.
  version: 1.0.0
servers:
  - url: https://uat-api.clinkbill.com/api/
security:
  - ApiKeyAuth: []
    timestamp: []
paths:
  /webhook/endpoints:
    post:
      summary: Create Webhook Endpoint
      description: >-
        Create a webhook endpoint for the current merchant. The endpoint URL
        must use HTTPS and resolve to a public host.
      operationId: createWebhookEndpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookEndpointCreateRequest'
            examples:
              example:
                value:
                  url: https://example.com/api/clink/webhook
                  events:
                    - session.complete
                    - order.succeeded
                    - invoice.paid
                  description: Created through the API
                  enabled: true
      responses:
        '200':
          description: Webhook endpoint created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RWebhookEndpointResponse'
              examples:
                example:
                  value:
                    code: 200
                    msg: Success
                    data:
                      id: whk_xxxxx
                      url: https://example.com/api/clink/webhook
                      events:
                        - session.complete
                        - order.succeeded
                        - invoice.paid
                      enabled: true
                      signingSecret: whsec_xxxxx
                      maskedSigningSecret: whsec_...abcd
                      description: Created through the API
                      createdAt: 1782112780956
                      updatedAt: 1782112780956
            '*/*':
              schema:
                $ref: '#/components/schemas/RWebhookEndpointResponse'
        '400':
          description: >-
            Invalid URL, unsupported event name, duplicate URL, or invalid
            request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClinkErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClinkErrorResponse'
components:
  schemas:
    WebhookEndpointCreateRequest:
      type: object
      required:
        - url
        - events
      properties:
        url:
          type: string
          format: uri
          maxLength: 512
          description: >-
            HTTPS endpoint URL. Localhost, loopback IPs, private IPs, link-local
            addresses, and multicast addresses are rejected.
          example: https://example.com/api/clink/webhook
        events:
          type: array
          minItems: 1
          description: Event names to subscribe to. Numeric event codes are not accepted.
          items:
            $ref: '#/components/schemas/WebhookEventName'
          example:
            - session.complete
            - order.succeeded
            - invoice.paid
        description:
          type: string
          maxLength: 512
          description: Optional endpoint description.
          example: Created through the API
        enabled:
          type: boolean
          default: true
          description: Whether the endpoint is enabled.
    RWebhookEndpointResponse:
      type: object
      properties:
        code:
          type: integer
          description: Response status code, 200 when success
          format: int32
          example: 200
        msg:
          type: string
          description: Brief description of what happened, 'success' when happy case
          example: Success
        data:
          $ref: '#/components/schemas/WebhookEndpointResponse'
      description: Body of the response message
    ClinkErrorResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: Error code returned by Clink.
        msg:
          type: string
          description: Error message.
        data:
          description: Additional error data, usually null.
    WebhookEventName:
      type: string
      description: >-
        Supported webhook event name. Public API requests use event names, not
        numeric event codes.
      enum:
        - order.created
        - order.succeeded
        - order.failed
        - refund.created
        - refund.succeeded
        - refund.failed
        - subscription.created
        - subscription.trialing
        - subscription.activated
        - subscription.incomplete_expired
        - subscription.past_due
        - subscription.cancelled
        - invoice.open
        - invoice.paid
        - invoice.void
        - order.next_action
        - subscription.updated.plan_changed
        - subscription.updated.plan_change_canceled
        - subscription.updated.renewed
        - subscription.updated.cancel_at_period_end_set
        - subscription.updated.cancel_at_period_end_revoked
        - session.complete
        - session.expired
        - dispute.created
        - dispute.updated
        - dispute.won
        - dispute.lost
        - dispute.closed
        - customer.verify
        - payment_method.added
        - payment_method.default_change
        - risk_rule.updated
        - agent_order.succeeded
        - agent_order.failed
        - agent_refund.succeeded
        - agent_refund.failed
        - agent_refund.approved
        - agent_refund.rejected
        - payment_method.update
        - purchase_instruction.created
        - purchase_instruction.activated
        - purchase_instruction.updated
        - purchase_instruction.cancelled
        - vic_device.binding_succeeded
    WebhookEndpointResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the webhook endpoint.
          example: whk_xxxxx
        url:
          type: string
          format: uri
          description: HTTPS URL that receives webhook events.
          example: https://example.com/api/clink/webhook
        events:
          type: array
          description: >-
            Event names subscribed by this endpoint. Responses always return
            event names.
          items:
            $ref: '#/components/schemas/WebhookEventName'
          example:
            - session.complete
            - order.succeeded
        enabled:
          type: boolean
          description: Whether this endpoint is active.
          example: true
        signingSecret:
          type:
            - string
            - 'null'
          description: >-
            Plaintext signing secret. Returned only when a secret is newly
            created or rotated; otherwise null.
          example: whsec_xxxxx
        maskedSigningSecret:
          type:
            - string
            - 'null'
          description: Masked signing secret for display.
          example: whsec_...abcd
        description:
          type:
            - string
            - 'null'
          description: Optional endpoint description.
          example: Created through the API
        createdAt:
          type:
            - integer
            - 'null'
          format: int64
          description: Creation time as a 13-digit Unix timestamp in milliseconds.
          example: 1782112780956
        updatedAt:
          type:
            - integer
            - 'null'
          format: int64
          description: Last update time as a 13-digit Unix timestamp in milliseconds.
          example: 1782113780956
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Your secret API key obtained from the Clink dashboard (Developers
        section)
    timestamp:
      type: apiKey
      in: header
      name: X-Timestamp
      description: >-
        Current timestamp in milliseconds since Unix epoch (required for request
        signing)

````