> ## 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. # Create an Endpoint > Register an HTTPS URL to receive the events you choose. Creates an endpoint and returns it with a one-time `signing_secret` (`whsec_…`) and status `201`. Store the secret right away: a retry with the same `Idempotency-Key` returns `200` with `"replayed": true` and doesn't return the secret again. New endpoints start **paused and unverified**. Before Prava delivers events: 1. [Verify the endpoint](https://docs.prava.space/api-reference/webhooks/verify-endpoint.md) so Prava knows your receiver controls the URL. 2. [Update it](https://docs.prava.space/api-reference/webhooks/update-endpoint.md) with `"enabled": true`. ```bash theme={null} curl https://sandbox.api.prava.space/v1/webhook-endpoints \ -H 'Authorization: Bearer YOUR_SECRET_KEY' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: register-receiver-0001' \ -d '{"name":"Payments","url":"https://api.example.com/prava/webhooks","events":["payment.succeeded","payment.failed"]}' ``` | Error | Meaning | | - | - | | `409 IDEMPOTENCY_CONFLICT` | The `Idempotency-Key` was already used with a different request body. | | `409 WEBHOOK_ENDPOINT_LIMIT` | This environment already has five endpoints. Delete one first. | ## OpenAPI ````yaml api-reference/openapi.json POST /v1/webhook-endpoints 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: post: tags: - Webhooks summary: POST /v1/webhook-endpoints description: >- Gated preview; application and environment are derived from the secret key. See the Webhooks guide for delivery and signing contracts. parameters: - name: Idempotency-Key in: header required: true schema: type: string pattern: ^[A-Za-z0-9_-]{8,120}$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointInput' responses: '200': description: >- Successful operation; endpoints never include stored signing secrets. content: application/json: schema: type: object required: - endpoint - replayed properties: endpoint: $ref: '#/components/schemas/WebhookEndpoint' replayed: type: boolean const: true description: >- A retry with the same `Idempotency-Key`. The secret isn't returned again. '201': description: >- Paused endpoint and one-time signing_secret. Idempotent retry returns 200 without signing_secret. content: application/json: schema: type: object required: - endpoint - signing_secret properties: endpoint: $ref: '#/components/schemas/WebhookEndpoint' signing_secret: type: string description: Returned only on this response. Store it securely. examples: - whsec_… '400': description: Invalid input or cursor '404': description: Resource not found in this application '409': description: Verification, idempotency, or endpoint state conflict '503': description: Preview disabled or temporarily unavailable components: schemas: WebhookEndpointInput: type: object additionalProperties: false required: - name - url - events properties: name: type: string minLength: 1 maxLength: 80 url: type: string format: uri maxLength: 2048 description: Public HTTPS port 443, no query, userinfo or redirects. events: type: array minItems: 1 maxItems: 16 uniqueItems: true items: 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 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.