Create a Webhook Endpoint — POST /webhooks

Registers an endpoint that Blockra will POST events to. Requires the webhooks:write scope. See Webhooks for the payload shape and signature verification.

The signing secret (whsec_…) is returned once, in this response, and never again. Store it securely — you need it to verify webhook signatures.

Request

POST https://api.blockra.io/webhooks

Body parameters

url

string

required

The HTTPS endpoint to deliver events to.

events

array

required

The events to subscribe to. One or more of payment.created, payment.confirming, payment.completed, payment.expired, payment.refunded, payout.completed.

Response

string

The endpoint ID, prefixed whk_.

url

string

The delivery URL.

events

array

The subscribed events.

secret

string

The signing secret (whsec_…). Returned only here, on creation.

is_active

boolean

Whether the endpoint is receiving events.

created_at

string

ISO-8601 creation time.

curl https://api.blockra.io/webhooks \
  -X POST \
  -H "X-API-Key: bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-site.com/webhooks/blockra",
    "events": ["payment.completed", "payment.expired"]
  }'

{
  "data": {
    "id": "whk_3n4o5p6q7r8s9t0u",
    "url": "https://your-site.com/webhooks/blockra",
    "events": ["payment.completed", "payment.expired"],
    "secret": "whsec_9a8b7c6d5e4f3g2h1i0j...",
    "is_active": true,
    "created_at": "2026-07-09T02:45:00.000Z"
  },
  "error": null
}

List WebhooksPage through your registered webhook endpoints. Secrets are never returned. Requires webhooks:read.

curl https://api.blockra.io/webhooks \
  -X POST \
  -H "X-API-Key: bk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-site.com/webhooks/blockra",
    "events": ["payment.completed", "payment.expired"]
  }'

{
  "data": {
    "id": "whk_3n4o5p6q7r8s9t0u",
    "url": "https://your-site.com/webhooks/blockra",
    "events": ["payment.completed", "payment.expired"],
    "secret": "whsec_9a8b7c6d5e4f3g2h1i0j...",
    "is_active": true,
    "created_at": "2026-07-09T02:45:00.000Z"
  },
  "error": null
}

​Request

​Body parameters

​Response

Request

Body parameters

Response