# Webhooks and Events API Reference

REST schemas and generated examples for webhook endpoint registration and delivery management.

<!-- docs-source -->
Source: https://learning.monetizekit.app/docs/api-reference/webhooks
<!-- /docs-source -->

Mock API reference used by the interactive docs explorer.

| OpenAPI version | Contract version | REST base path |
| --- | --- | --- |
| 3.1.0 | 2026-03-15 | /api/v1 |

## Servers

| URL | Environment |
| --- | --- |
| `https://app.monetizekit.app/api/v1` | Development environment |
| `https://app.monetizekit.app/api/v1` | Staging environment |
| `https://app.monetizekit.app/api/v1` | Production environment |

## webhooks operations

### List webhook endpoints

`GET /webhooks/endpoints` — Returns configured webhook endpoints.

Operation ID: listWebhookEndpoints.

Required scopes: webhooks:read.

#### Responses

`200` — Success

```json
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        }
      }
    }
  }
}
```

```json
{
  "data": [
    {
      "id": "wh_001",
      "url": "https://example.local/hooks/monetizekit"
    }
  ]
}
```

### Create webhook endpoint

`POST /webhooks/endpoints` — Registers a new webhook endpoint.

Operation ID: createWebhookEndpoint.

Required scopes: webhooks:write.

#### Request schema

```json
{
  "type": "object",
  "required": [
    "url",
    "events"
  ],
  "properties": {
    "url": {
      "type": "string"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}
```

#### Request example

```json
{
  "url": "https://example.local/hooks/monetizekit",
  "events": [
    "customer.created"
  ]
}
```

#### Responses

`201` — Created

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "secret": {
      "type": "string"
    }
  }
}
```

```json
{
  "id": "wh_002",
  "secret": "whsec_placeholder"
}
```