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

# Verify an Endpoint

> Prove that your receiver controls the endpoint URL.

Prava sends a signed challenge to the endpoint URL. Your receiver should check the signature and respond with a `2xx` JSON body that echoes the exact `challenge` value. On success, the response returns the endpoint with `verified_at` set, and you can enable it.

| Error | Meaning |
| - | - |
| `409 WEBHOOK_CHALLENGE_FAILED` | The response didn't echo the `challenge` value in a complete JSON body. |
| `409 WEBHOOK_DESTINATION_CHANGED` | The endpoint URL changed while verification was running. Verify again. |
| `422 WEBHOOK_RECEIVER_UNAVAILABLE` | Prava couldn't reach the receiver securely. Check its public DNS, HTTPS certificate and availability. |

See [Security](https://docs.prava.space/webhooks/security.md) for signature verification and [Receiver examples](https://docs.prava.space/webhooks/receiver-examples.md) for working handlers.


## OpenAPI

````yaml api-reference/openapi.json POST /v1/webhook-endpoints/{endpointId}/verify
openapi: 3.1.0
info:
  title: Prava Payments API
  description: >-
    Server-side REST API for Prava Payments. All requests are authenticated with
    your secret key (sk_test_* in sandbox, sk_live_* in production).
  version: 1.0.0
servers:
  - url: https://sandbox.api.prava.space
    description: Sandbox
  - url: https://api.prava.space
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/webhook-endpoints/{endpointId}/verify:
    post:
      tags:
        - Webhooks
      summary: POST /v1/webhook-endpoints/{endpointId}/verify
      description: >-
        Gated preview; application and environment are derived from the secret
        key. See the Webhooks guide for delivery and signing contracts.
      parameters:
        - name: endpointId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >-
            Successful operation; endpoints never include stored signing
            secrets.
          content:
            application/json:
              schema:
                type: object
                required:
                  - endpoint
                properties:
                  endpoint:
                    $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          description: Invalid input or cursor
        '404':
          description: Resource not found in this application
        '409':
          description: Verification, idempotency, or endpoint state conflict
        '422':
          description: >-
            WEBHOOK_RECEIVER_UNAVAILABLE: public receiver DNS, HTTPS or
            availability failure; safe actionable error without receiver
            diagnostics
        '503':
          description: Preview disabled or temporarily unavailable
components:
  schemas:
    WebhookEndpoint:
      type: object
      required:
        - id
        - owner_id
        - environment
        - name
        - url
        - events
        - revision
        - enabled
        - verified_at
        - deleted_at
        - created_at
        - schema_version
        - consecutive_failures
        - circuit_until
        - blocked_reason
      properties:
        id:
          type: string
          description: Endpoint ID, starting with `whe_`.
          examples:
            - whe_0123456789abcdef0123456789abcdef
        owner_id:
          type: string
          description: Your application's account ID, starting with `ma_`.
        environment:
          type: string
          enum:
            - sandbox
            - production
        name:
          type: string
          minLength: 1
          maxLength: 80
        url:
          type: string
          format: uri
          description: The HTTPS URL that receives events.
        events:
          type: array
          items:
            $ref: '#/components/schemas/WebhookEventType'
          description: Event types sent to this endpoint.
        revision:
          type: string
          description: Increases by one each time the URL changes. Returned as a string.
        enabled:
          type: boolean
          description: Whether new events are delivered. New endpoints start with `false`.
        verified_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When verification succeeded. Cleared when the URL changes.
        deleted_at:
          type:
            - string
            - 'null'
          format: date-time
          description: '`null` for active endpoints.'
          examples:
            - null
        created_at:
          type: string
          format: date-time
        schema_version:
          type: string
          description: Payload schema version sent to this endpoint.
          examples:
            - '2026-10-08'
        consecutive_failures:
          type: integer
          minimum: 0
          description: Failed deliveries in a row. Resets after a delivery is accepted.
          examples:
            - 0
        circuit_until:
          type:
            - string
            - 'null'
          format: date-time
          description: Deliveries are held until this time after repeated failures.
          examples:
            - null
        blocked_reason:
          type:
            - string
            - 'null'
          enum:
            - RECEIVER_UNACKNOWLEDGED
            - DELIVERY_FAILURE_LIMIT
            - HTTP_GONE
            - DESTINATION_BLOCKED
            - null
          description: >-
            Why Prava paused deliveries, or `null`. See [Endpoint health
            reasons](/webhooks/delivery#endpoint-health-reasons).
          examples:
            - null
    WebhookEventType:
      type: string
      enum:
        - payment.credentials_ready
        - payment.succeeded
        - payment.failed
        - card_enrollment.completed
        - card_enrollment.failed
        - card_enrollment.cancelled
        - card_enrollment.expired
        - mandate.created
        - mandate.creation_failed
        - mandate.creation_cancelled
        - mandate.creation_expired
        - mandate.paused
        - mandate.resumed
        - mandate.cancelled
        - mandate.expired
        - quote.request_failed
      description: A webhook event type.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your secret key: sk_test_* (sandbox) or sk_live_* (production).'

````

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