# webhooks (Coinbax API)

> Source: https://developers.coinbax.com/reference/coinbax-api/webhooks/
> Staging base URL: https://api-staging.coinbax.com

## List webhook subscriptions

`GET /api/v1/webhooks`

- Auth: X-API-Key header
- Operation ID: `WebhookController_list`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `isActive` | query | string | yes |  |
| `eventType` | query | string | yes |  |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/webhooks?isActive=<isActive>&eventType=<eventType> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** List of webhook subscriptions

---

## Create webhook subscription

`POST /api/v1/webhooks`

- Auth: X-API-Key header
- Operation ID: `WebhookController_create`

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | yes | The URL to send webhook events to |
| `eventTypes` | array of string | yes | Event types to subscribe to |
| `ipWhitelist` | array of string | no | Optional list of IP addresses allowed to send webhooks |
| `metadata` | object | no | Optional metadata for the subscription |

```json
{
  "url": "https://api.example.com/webhooks",
  "eventTypes": [
    "transaction.created",
    "transaction.completed"
  ],
  "ipWhitelist": [
    "1.2.3.4",
    "5.6.7.8"
  ],
  "metadata": {
    "environment": "production",
    "team": "payments"
  }
}
```

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/webhooks \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://api.example.com/webhooks",
  "eventTypes": [
    "transaction.created",
    "transaction.completed"
  ],
  "ipWhitelist": [
    "1.2.3.4",
    "5.6.7.8"
  ],
  "metadata": {
    "environment": "production",
    "team": "payments"
  }
}'
```

### Responses

**201** Webhook subscription created successfully

**400** Invalid event types

**401** Unauthorized

---

## Get available webhook event types

`GET /api/v1/webhooks/events/types`

- Auth: X-API-Key header
- Operation ID: `WebhookController_getEventTypes`

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/webhooks/events/types \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** List of available event types

---

## Get webhook subscription

`GET /api/v1/webhooks/{id}`

- Auth: X-API-Key header
- Operation ID: `WebhookController_get`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/webhooks/<id> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Webhook subscription details

**404** Subscription not found

---

## Delete webhook subscription

`DELETE /api/v1/webhooks/{id}`

- Auth: X-API-Key header
- Operation ID: `WebhookController_delete`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Example request

```bash
curl -X DELETE https://api-staging.coinbax.com/api/v1/webhooks/<id> \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Webhook subscription deleted

**404** Subscription not found

---

## Update webhook subscription

`PATCH /api/v1/webhooks/{id}`

- Auth: X-API-Key header
- Operation ID: `WebhookController_update`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string | no | The URL to send webhook events to |
| `eventTypes` | array of string | no | Event types to subscribe to |
| `isActive` | boolean | no | Whether the subscription is active |
| `ipWhitelist` | array of string | no | Optional list of IP addresses allowed to send webhooks |
| `metadata` | object | no | Optional metadata for the subscription |

```json
{
  "url": "https://api.example.com/webhooks/v2",
  "eventTypes": [
    "transaction.created",
    "transaction.completed",
    "transaction.refunded"
  ],
  "isActive": true,
  "ipWhitelist": [
    "1.2.3.4",
    "5.6.7.8"
  ],
  "metadata": {
    "environment": "production",
    "team": "payments"
  }
}
```

### Example request

```bash
curl -X PATCH https://api-staging.coinbax.com/api/v1/webhooks/<id> \
  -H "X-API-Key: $COINBAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://api.example.com/webhooks/v2",
  "eventTypes": [
    "transaction.created",
    "transaction.completed",
    "transaction.refunded"
  ],
  "isActive": true,
  "ipWhitelist": [
    "1.2.3.4",
    "5.6.7.8"
  ],
  "metadata": {
    "environment": "production",
    "team": "payments"
  }
}'
```

### Responses

**200** Webhook subscription updated

**400** Invalid event types

**404** Subscription not found

---

## Complete secret rotation

`POST /api/v1/webhooks/{id}/complete-rotation`

- Auth: X-API-Key header
- Operation ID: `WebhookController_completeRotation`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/webhooks/<id>/complete-rotation \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Secret rotation completed

**400** No rotation in progress

**404** Subscription not found

---

## Get webhook delivery logs

`GET /api/v1/webhooks/{id}/delivery-logs`

- Auth: X-API-Key header
- Operation ID: `WebhookController_deliveryLogs`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |
| `limit` | query | number | no | Number of logs to return |
| `offset` | query | number | no | Number of logs to skip |
| `successOnly` | query | boolean | no | Filter for successful deliveries only |
| `failuresOnly` | query | boolean | no | Filter for failed deliveries only |

### Example request

```bash
curl https://api-staging.coinbax.com/api/v1/webhooks/<id>/delivery-logs \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Delivery logs with pagination

**404** Subscription not found

---

## Reset circuit breaker

`POST /api/v1/webhooks/{id}/reset-circuit-breaker`

- Auth: X-API-Key header
- Operation ID: `WebhookController_resetCircuitBreaker`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/webhooks/<id>/reset-circuit-breaker \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Circuit breaker reset

**404** Subscription not found

---

## Rotate webhook secret

`POST /api/v1/webhooks/{id}/rotate-secret`

- Auth: X-API-Key header
- Operation ID: `WebhookController_rotateSecret`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/webhooks/<id>/rotate-secret \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Secret rotation initiated

**404** Subscription not found

---

## Test webhook endpoint

`POST /api/v1/webhooks/{id}/test`

- Auth: X-API-Key header
- Operation ID: `WebhookController_test`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Subscription ID |

### Example request

```bash
curl -X POST https://api-staging.coinbax.com/api/v1/webhooks/<id>/test \
  -H "X-API-Key: $COINBAX_API_KEY"
```

### Responses

**200** Test result

**404** Subscription not found