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

# Retrieve a Webhook Endpoint by ID

> Retrieve a webhook endpoint by its ID.

Use this endpoint to retrieve a single webhook endpoint by its ID. The response carries the endpoint's URL, its subscribed events, its `apiVersion`, and its current state.

The signing secret is not part of the response. It is returned only when the endpoint is created, so if you no longer hold it, [delete the endpoint and register a replacement](/concepts/webhooks/managing-endpoints#updating-an-endpoint-delete-and-recreate) to obtain a fresh one.


## OpenAPI

````yaml openapi/spherepay.yaml GET /v2/webhook-endpoints/{id}
openapi: 3.0.0
info:
  contact: {}
  description: The Sphere REST API for payments, transfers, and accounts.
  title: Sphere API
  version: '2'
servers:
  - description: Production
    url: https://api.spherepay.co
security:
  - bearer: []
tags: []
paths:
  /v2/webhook-endpoints/{id}:
    get:
      summary: Get a Webhook Endpoint V2
      description: Retrieve a webhook endpoint by its ID.
      operationId: getV2WebhookEndpointsById
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  apiVersion:
                    description: >-
                      API version date string this endpoint was configured with,
                      or null if not set.
                    example: '2026-04-01'
                    nullable: true
                    type: string
                  createdAt:
                    description: ISO 8601 timestamp when the endpoint was created.
                    example: '2026-01-01T00:00:00.000Z'
                    type: string
                  description:
                    description: >-
                      Human-readable description of this webhook endpoint, or
                      null if not set.
                    example: Production payment events handler
                    nullable: true
                    type: string
                  id:
                    description: The unique identifier of the webhook endpoint.
                    example: webhook_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
                    type: string
                  metadata:
                    description: >-
                      Arbitrary key-value metadata attached to this endpoint, or
                      null if not set.
                    example:
                      environment: prod
                      team: payments
                    nullable: true
                  status:
                    description: The current state of this endpoint.
                    enum:
                      - enabled
                      - errored
                      - disabled
                      - deleted
                    example: enabled
                    type: string
                    x-enumNames:
                      - ENABLED
                      - ERRORED
                      - DISABLED
                      - DELETED
                  subscribedEvents:
                    description: List of event types this endpoint receives.
                    example:
                      - customer.created
                      - transfer.succeeded
                    items:
                      enum:
                        - '*'
                        - customer.*
                        - transfer.*
                        - document.*
                        - service.*
                        - customer.created
                        - customer.pending
                        - customer.approved
                        - customer.rejected
                        - transfer.created
                        - transfer.pendingFunding
                        - transfer.pendingReview
                        - transfer.fundsReceived
                        - transfer.processing
                        - transfer.succeeded
                        - transfer.returned
                        - transfer.pendingRefundInformation
                        - transfer.failed
                        - transfer.canceled
                        - transfer.refunded
                        - transfer.unexpectedError
                        - transfer.failedPrecondition
                        - transfer.expired
                        - transfer.unfunded
                        - document.pending
                        - document.processing
                        - document.verified
                        - document.rejected
                        - service.pending
                        - service.processing
                        - service.succeeded
                        - service.failed
                        - service.cancelled
                      type: string
                      x-enumNames:
                        - ALL
                        - ALL_CUSTOMER
                        - ALL_TRANSFER
                        - ALL_DOCUMENT
                        - ALL_SERVICE
                        - CREATE_CUSTOMER
                        - PENDING_CUSTOMER
                        - APPROVE_CUSTOMER
                        - REJECT_CUSTOMER
                        - CREATE_TRANSFER
                        - PENDING_FUNDING_TRANSFER
                        - PENDING_REVIEW_TRANSFER
                        - FUNDS_RECEIVED_TRANSFER
                        - PROCESSING_TRANSFER
                        - SUCCESSFUL_TRANSFER
                        - RETURNED_TRANSFER
                        - PENDING_REFUND_INFORMATION_TRANSFER
                        - FAILED_TRANSFER
                        - CANCELLED_TRANSFER
                        - REFUNDED_TRANSFER
                        - UNEXPECTED_ERROR_TRANSFER
                        - FAILED_PRECONDITION_TRANSFER
                        - EXPIRED_TRANSFER
                        - UNFUNDED_TRANSFER
                        - PENDING_DOCUMENT
                        - PROCESSING_DOCUMENT
                        - VERIFIED_DOCUMENT
                        - REJECTED_DOCUMENT
                        - PENDING_SERVICE
                        - PROCESSING_SERVICE
                        - SUCCESSFUL_SERVICE
                        - FAILED_SERVICE
                        - CANCELLED_SERVICE
                    type: array
                  updatedAt:
                    description: ISO 8601 timestamp when the endpoint was last updated.
                    example: '2026-01-01T00:00:00.000Z'
                    type: string
                  url:
                    description: The HTTPS URL events are delivered to.
                    example: https://example.com/webhooks/sphere
                    type: string
                required:
                  - id
                  - url
                  - subscribedEvents
                  - status
                  - apiVersion
                  - description
                  - metadata
                  - createdAt
                  - updatedAt
                type: object
          description: The requested webhook endpoint.
        '400':
          content:
            application/json:
              examples:
                Bad Request:
                  summary: Bad Request
                  value:
                    code: address/invalid
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Invalid request parameters
                    status: 400
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Bad Request
        '404':
          content:
            application/json:
              examples:
                Not Found:
                  summary: Not Found
                  value:
                    code: resource/not-found
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Resource not found
                    status: 404
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Not Found
        '422':
          content:
            application/json:
              examples:
                Validation Error:
                  summary: Validation Error
                  value:
                    code: validation/failed
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Validation failed
                    errors:
                      - detail: Invalid email format
                        pointer: /email
                      - detail: Name is required
                        pointer: /name
                    status: 422
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Unprocessable Entity - Validation Error
components:
  schemas:
    ProblemDetailsDto:
      properties:
        code:
          type: string
        correlationId:
          type: string
        detail:
          type: string
        errors:
          items:
            properties:
              detail:
                type: string
              header:
                type: string
              parameter:
                type: string
              pointer:
                type: string
            required:
              - detail
            type: object
          type: array
        status:
          type: integer
        title:
          type: string
      required:
        - status
        - detail
      type: object
  securitySchemes:
    bearer:
      bearerFormat: JWT
      scheme: bearer
      type: http

````