Create an Endpoint

POST /v1/webhook-endpoints

curl --request POST \
  --url https://sandbox.api.prava.space/v1/webhook-endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "<string>",
  "url": "<string>",
  "events": []
}
'

import requests

url = "https://sandbox.api.prava.space/v1/webhook-endpoints"

payload = {
    "name": "<string>",
    "url": "<string>",
    "events": []
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: '<string>', url: '<string>', events: []})
};

fetch('https://sandbox.api.prava.space/v1/webhook-endpoints', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "endpoint": {
    "id": "whe_0123456789abcdef0123456789abcdef",
    "owner_id": "<string>",
    "environment": "sandbox",
    "name": "<string>",
    "url": "<string>",
    "events": [
      "payment.credentials_ready"
    ],
    "revision": "<string>",
    "enabled": true,
    "verified_at": "2023-11-07T05:31:56Z",
    "deleted_at": null,
    "created_at": "2023-11-07T05:31:56Z",
    "schema_version": "2026-10-08",
    "consecutive_failures": 0,
    "circuit_until": null,
    "blocked_reason": null
  },
  "replayed": true
}

{
  "endpoint": {
    "id": "whe_0123456789abcdef0123456789abcdef",
    "owner_id": "<string>",
    "environment": "sandbox",
    "name": "<string>",
    "url": "<string>",
    "events": [
      "payment.credentials_ready"
    ],
    "revision": "<string>",
    "enabled": true,
    "verified_at": "2023-11-07T05:31:56Z",
    "deleted_at": null,
    "created_at": "2023-11-07T05:31:56Z",
    "schema_version": "2026-10-08",
    "consecutive_failures": 0,
    "circuit_until": null,
    "blocked_reason": null
  },
  "signing_secret": "whsec_…"
}

POST

webhook-endpoints

POST /v1/webhook-endpoints

curl --request POST \
  --url https://sandbox.api.prava.space/v1/webhook-endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "<string>",
  "url": "<string>",
  "events": []
}
'

import requests

url = "https://sandbox.api.prava.space/v1/webhook-endpoints"

payload = {
    "name": "<string>",
    "url": "<string>",
    "events": []
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({name: '<string>', url: '<string>', events: []})
};

fetch('https://sandbox.api.prava.space/v1/webhook-endpoints', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "endpoint": {
    "id": "whe_0123456789abcdef0123456789abcdef",
    "owner_id": "<string>",
    "environment": "sandbox",
    "name": "<string>",
    "url": "<string>",
    "events": [
      "payment.credentials_ready"
    ],
    "revision": "<string>",
    "enabled": true,
    "verified_at": "2023-11-07T05:31:56Z",
    "deleted_at": null,
    "created_at": "2023-11-07T05:31:56Z",
    "schema_version": "2026-10-08",
    "consecutive_failures": 0,
    "circuit_until": null,
    "blocked_reason": null
  },
  "replayed": true
}

{
  "endpoint": {
    "id": "whe_0123456789abcdef0123456789abcdef",
    "owner_id": "<string>",
    "environment": "sandbox",
    "name": "<string>",
    "url": "<string>",
    "events": [
      "payment.credentials_ready"
    ],
    "revision": "<string>",
    "enabled": true,
    "verified_at": "2023-11-07T05:31:56Z",
    "deleted_at": null,
    "created_at": "2023-11-07T05:31:56Z",
    "schema_version": "2026-10-08",
    "consecutive_failures": 0,
    "circuit_until": null,
    "blocked_reason": null
  },
  "signing_secret": "whsec_…"
}

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:

Verify the endpoint so Prava knows your receiver controls the URL.
Update it with "enabled": true.

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.

Authorizations

Authorization

string

header

required

Your secret key: sk_test_* (sandbox) or sk_live_* (production).

Headers

Idempotency-Key

string

required

Pattern: ^[A-Za-z0-9_-]{8,120}$

Body

application/json

name

string

required

Required string length: 1 - 80

url

string<uri>

required

Public HTTPS port 443, no query, userinfo or redirects.

Maximum string length: 2048

events

enum<string>[]

required

Required array length: 1 - 16 elements

Available options:

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

Response

Successful operation; endpoints never include stored signing secrets.

endpoint

object

required

Show child attributes

replayed

boolean

required

A retry with the same Idempotency-Key. The secret isn't returned again.

Server-Side API

Webhooks API

Reference

Authorizations

Headers

Body

Response