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

# Create a Webhook Endpoint — POST /webhooks

> Register an endpoint to receive payment events. The signing secret is returned once, here. Requires webhooks:write.

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

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

## Request

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

### Body parameters

<ParamField body="url" type="string" required>
  The HTTPS endpoint to deliver events to.
</ParamField>

<ParamField body="events" type="array" required>
  The events to subscribe to. One or more of `payment.created`, `payment.confirming`, `payment.completed`, `payment.expired`, `payment.refunded`, `payout.completed`.
</ParamField>

## Response

<ResponseField name="id" type="string">
  The endpoint ID, prefixed `whk_`.
</ResponseField>

<ResponseField name="url" type="string">
  The delivery URL.
</ResponseField>

<ResponseField name="events" type="array">
  The subscribed events.
</ResponseField>

<ResponseField name="secret" type="string">
  The signing secret (`whsec_…`). Returned only here, on creation.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Whether the endpoint is receiving events.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO-8601 creation time.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "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
  }
  ```
</ResponseExample>