> For the complete index of the 402pay docs, see [llms.txt](https://developer.402pay.co/llms.txt).

# Create a webhook endpoint

Add an endpoint for the events you choose and get its signing secret.

`POST https://dash.402pay.co/api/v1/webhooks`

This is the only response that includes the signing `secret`, so store it now. Every other response shows only `secret_hint`.

### Body

- `url` (string, required): An https:// address on the public internet, up to 2048 characters. Private, loopback and link-local hosts are refused.
- `event_types` (array, required): The types to receive, at least one. See [event types](https://developer.402pay.co/guides/webhook-events.md#event-types).
- `description` (string): A note for your team, up to 120 characters.
- `enabled` (boolean): Defaults to `true`.

### Errors

- 400 `invalid_request` A field is missing, unknown or out of range. `field` names it.

Any request can also fail on its key or its body. See [errors](https://developer.402pay.co/api/errors.md).

Request, cURL:

```bash
curl -X POST "https://dash.402pay.co/api/v1/webhooks" \
  -H "Authorization: Bearer $PAY402_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/402pay",
    "description": "Fulfill orders",
    "event_types": ["payment.succeeded", "payment.failed"]
  }'
```

Request, Node.js:

```js
const response = await fetch("https://dash.402pay.co/api/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAY402_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/webhooks/402pay",
    description: "Fulfill orders",
    event_types: ["payment.succeeded", "payment.failed"]
  }),
});
const { data } = await response.json();
```

Request, Python:

```python
import os

import requests

response = requests.post(
    "https://dash.402pay.co/api/v1/webhooks",
    headers={
        "Authorization": f"Bearer {os.environ['PAY402_SECRET_KEY']}",
    },
    json={
        "url": "https://example.com/webhooks/402pay",
        "description": "Fulfill orders",
        "event_types": ["payment.succeeded", "payment.failed"]
    },
)
data = response.json()["data"]
```

Response, 201 Created:

```json
{
  "data": {
    "id": "whk_GFAKLrE8wkBwF4WL",
    "kind": "webhook",
    "url": "https://example.com/webhooks/402pay",
    "description": "Fulfill orders",
    "event_types": ["payment.succeeded", "payment.failed"],
    "enabled": true,
    "secret_hint": "whsec_••••X/LG",
    "created_at": "2026-09-26T21:22:47.012Z",
    "updated_at": "2026-09-26T21:22:47.012Z",
    "secret": "whsec_bM0XCID9vQtL0CuhH+4f/aQMZm7pX/LG"
  }
}
```