# Webhooks

<a id="get-api-v1-system-webhooks"></a>
#### `GET /api/v1/system/webhooks`

*List webhook endpoints*

Return every registered webhook subscriber.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_list_dict_str__Any___` | Successful Response |

**Response example (200):**

```json
{
  "data": [
    {}
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks
```

---

<a id="post-api-v1-system-webhooks"></a>
#### `POST /api/v1/system/webhooks`

*Create webhook endpoint*

Register a new subscriber. The plaintext ``secret`` is returned ONLY on this response; rotate via ``/rotate`` to mint a new one.

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `description` | string | no | default `` |
| `enabled` | boolean | no | default `True` |
| `events` | array<string> | no | — |
| `secret` | string | no | — |
| `url` | string | yes | — |

**Request body example:**

```json
{
  "description": "",
  "enabled": true,
  "events": [
    "string"
  ],
  "secret": "string",
  "url": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/system/webhooks
```

---

<a id="get-api-v1-system-webhooks-deliveries"></a>
#### `GET /api/v1/system/webhooks/deliveries`

*List webhook deliveries*

Paginated history of delivery attempts (success, failed, dead-letter).

**Query parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `limit` | integer | no | minimum=1; maximum=500 |
| `offset` | integer | no | minimum=0 |
| `endpoint_id` | string | no | — |
| `status` | string | no | — |
| `event_type` | string | no | — |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/deliveries
```

---

<a id="get-api-v1-system-webhooks-deliveries-delivery-id"></a>
#### `GET /api/v1/system/webhooks/deliveries/{delivery_id}`

*Get delivery detail*

Return the full record (payload + response excerpt) for a single delivery attempt.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `delivery_id` | string | yes | pattern=`^dlv_[a-f0-9]+$` |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/deliveries/{delivery_id}
```

---

<a id="post-api-v1-system-webhooks-deliveries-delivery-id-retry"></a>
#### `POST /api/v1/system/webhooks/deliveries/{delivery_id}/retry`

*Retry delivery*

Re-enqueue a failed / dead-letter delivery at its own endpoint. A new delivery id is minted and the original record stays for audit; 404 when the endpoint is gone, 409 WEBHOOK_DISABLED while it is disabled or muted.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `delivery_id` | string | yes | pattern=`^dlv_[a-f0-9]+$` |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/deliveries/{delivery_id}/retry
```

---

<a id="get-api-v1-system-webhooks-events"></a>
#### `GET /api/v1/system/webhooks/events`

*List webhook event types*

Return the catalog of every event a webhook endpoint can subscribe to.

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_list_dict_str__Any___` | Successful Response |

**Response example (200):**

```json
{
  "data": [
    {}
  ],
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/events
```

---

<a id="delete-api-v1-system-webhooks-endpoint-id"></a>
#### `DELETE /api/v1/system/webhooks/{endpoint_id}`

*Delete webhook endpoint*

Permanently remove a subscriber. Pending queued events for this endpoint are dropped on the next dispatcher tick.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `endpoint_id` | string | yes | pattern=`^whk_[a-f0-9]+$` |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `MessageResponse` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "message": "string",
  "status": "success"
}
```

**cURL example:**

```bash
curl -X DELETE \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/{endpoint_id}
```

---

<a id="get-api-v1-system-webhooks-endpoint-id"></a>
#### `GET /api/v1/system/webhooks/{endpoint_id}`

*Get webhook endpoint*

Fetch a single endpoint by id. The secret is masked.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `endpoint_id` | string | yes | pattern=`^whk_[a-f0-9]+$` |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X GET \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/{endpoint_id}
```

---

<a id="put-api-v1-system-webhooks-endpoint-id"></a>
#### `PUT /api/v1/system/webhooks/{endpoint_id}`

*Update webhook endpoint*

Update url, events, description, enabled flag, or mute window. Pass ``secret`` only when explicitly rotating.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `endpoint_id` | string | yes | pattern=`^whk_[a-f0-9]+$` |

**Body fields:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `description` | string | no | — |
| `enabled` | boolean | no | — |
| `events` | array<string> | no | — |
| `muted_until` | string | no | — |
| `secret` | string | no | — |
| `url` | string | no | — |

**Request body example:**

```json
{
  "description": "string",
  "enabled": false,
  "events": [
    "string"
  ],
  "muted_until": "string",
  "secret": "string",
  "url": "string"
}
```

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X PUT \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  -H "Content-Type: application/json" \
  -d @body.json \
  https://your-server:2000/api/v1/system/webhooks/{endpoint_id}
```

---

<a id="post-api-v1-system-webhooks-endpoint-id-rotate"></a>
#### `POST /api/v1/system/webhooks/{endpoint_id}/rotate`

*Rotate webhook secret*

Generate a new HMAC secret. The plaintext value is returned ONCE — store it on the subscriber immediately.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `endpoint_id` | string | yes | pattern=`^whk_[a-f0-9]+$` |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/{endpoint_id}/rotate
```

---

<a id="post-api-v1-system-webhooks-endpoint-id-test"></a>
#### `POST /api/v1/system/webhooks/{endpoint_id}/test`

*Send test event*

Enqueue a synthetic event addressed at this endpoint only (other subscribers of the same event do not receive it). A disabled or muted endpoint answers 409 WEBHOOK_DISABLED. Useful for confirming connectivity + signature validation on the subscriber side.

**Path parameters:**

| Name | Type | Required | Notes |
|------|------|----------|-------|
| `endpoint_id` | string | yes | pattern=`^whk_[a-f0-9]+$` |

**Responses:**

| Status | Schema | Description |
|--------|--------|-------------|
| `200` | `ApiSuccess_dict_str__Any__` | Successful Response |
| `422` | `HTTPValidationError` | Validation Error |

**Response example (200):**

```json
{
  "data": {},
  "message": "",
  "status": "success",
  "warnings": [
    "string"
  ]
}
```

**cURL example:**

```bash
curl -X POST \
  -H "X-WHost-Key: $WHOST_API_KEY" \
  -H "X-WHost-Timestamp: $(date +%s)" \
  -H "X-WHost-Nonce: $(openssl rand -hex 16)" \
  -H "X-WHost-Signature: $(compute_hmac)" \
  https://your-server:2000/api/v1/system/webhooks/{endpoint_id}/test
```

---