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

# Create a webhook endpoint

> POST /v1/webhook-endpoints registers an https endpoint for a list of event types and returns its signing secret once.

```
POST /v1/webhook-endpoints
```

**Scope:** `webhooks:manage`  ·  **Idempotency-Key:** not accepted

<ParamField body="url" type="string" required>
  An `https://` URL that resolves to a public address. Loopback, link-local and private addresses are refused.
</ParamField>

<ParamField body="subscribedEventTypes" type="string[]" required>
  At least one event type from the [catalog](/reference/webhooks#event-types), or `["*"]` for all.
</ParamField>

<ParamField body="description" type="string">A note for your team.</ParamField>

```bash theme={null}
curl -X POST https://api.stg.cleo-pay.com/v1/webhook-endpoints \
  --header "Authorization: Bearer $CLEO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://hooks.example.com/cleo",
    "subscribedEventTypes": ["payment.held", "payment.completed", "payment.failed", "payment.returned", "invoice.paid"],
    "description": "Production payments listener"
  }'
```

## Response

`201` with the endpoint and its `secret` (`whsec_...`). This is the only time the full secret is returned; afterwards only `secretLast4` is shown. Store it as a credential.

The route takes no `Idempotency-Key`, because a replay would have to store and return the secret again. If a create times out, call `GET /v1/webhook-endpoints` before you create another.


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