> ## 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. # Register a Webhook Endpoint for Event Delivery > Register a new webhook endpoint to receive event deliveries for the specified subscribed events. Use this endpoint to register a URL that SpherePay delivers events to, together with the list of events it should receive. Subscribe with exact event names from the [event catalog](/concepts/webhooks/event-catalog), or with a wildcard — `*` for everything, or a resource wildcard such as `customer.*`. A new endpoint is `enabled` immediately and starts receiving matching events. The signing secret (prefixed `whsec_`) is returned **exactly once**, in this response. No `GET` returns it and it cannot be retrieved later. Store it securely — you need it to [verify the signature](/concepts/webhooks/verifying-signatures) on every delivery. Each application may hold at most six active endpoints, counting the `enabled`, `disabled`, and `errored` states. Exceeding that returns `409`. There is no update operation, so changing a URL or a subscription means creating a replacement and deleting the old endpoint — see [managing endpoints](/concepts/webhooks/managing-endpoints#updating-an-endpoint-delete-and-recreate) for the zero-gap sequence. ## OpenAPI ````yaml openapi/spherepay.yaml POST /v2/webhook-endpoints 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: post: summary: Create a Webhook Endpoint V2 description: >- Register a new webhook endpoint to receive event deliveries for the specified subscribed events. operationId: postV2WebhookEndpoints parameters: [] requestBody: content: application/json: schema: properties: apiVersion: description: API version date string provided by the client. example: '2026-04-01' type: string description: description: Human-readable description of this webhook endpoint. example: Production payment events handler maxLength: 500 type: string metadata: additionalProperties: {} description: Arbitrary key-value metadata to attach to this endpoint. example: environment: prod team: payments type: object subscribedEvents: description: List of event types this endpoint should receive. example: - customer.created - transfer.succeeded items: type: string minItems: 1 type: array url: description: The HTTPS URL to deliver webhook events to. example: https://example.com/webhooks/sphere format: uri maxLength: 2048 type: string required: - url - subscribedEvents - apiVersion type: object required: true responses: '201': 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 secret: description: >- Signing secret for this endpoint. Returned only on creation and never retrievable afterwards. example: whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 type: string 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 - secret type: object description: >- The created webhook endpoint, including the signing secret. The secret is returned only here and cannot be retrieved again. '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 ````