# Workspace Webhooks (Coinbax Core API)

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

Webhook management for workspaces

## List webhook subscriptions

`GET /workspaces/{id}/webhooks`

- Auth: Bearer token
- Operation ID: `listWorkspaceWebhooks`

Get all webhook subscriptions for a workspace.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `isActive` | query | boolean | no | Filter by active status |
| `eventType` | query | string | no | Filter by event type |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Webhook subscriptions retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": [
    {
      "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "url": "https://example.com/webhooks/coinbax",
      "eventTypes": [
        "transaction.created",
        "transaction.completed",
        "transaction.failed"
      ],
      "secret": "string",
      "isActive": true,
      "ipWhitelist": [
        "192.168.1.1",
        "10.0.0.0/8"
      ],
      "metadata": {},
      "createdAt": "2026-01-15T12:00:00.000Z",
      "updatedAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Create webhook subscription

`POST /workspaces/{id}/webhooks`

- Auth: Bearer token
- Operation ID: `createWorkspaceWebhook`

Create a new webhook subscription for a workspace.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string (uri) | yes | Webhook endpoint URL |
| `eventTypes` | array of string | yes | Event types to subscribe to |
| `ipWhitelist` | array of string | no | IP addresses allowed to receive webhooks |
| `metadata` | object | no |  |

```json
{
  "url": "https://example.com/webhooks/coinbax",
  "eventTypes": [
    "transaction.created",
    "transaction.completed"
  ],
  "ipWhitelist": [
    "192.168.1.1"
  ]
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/coinbax",
  "eventTypes": [
    "transaction.created",
    "transaction.completed"
  ],
  "ipWhitelist": [
    "192.168.1.1"
  ]
}'
```

### Responses

**201** Webhook subscription created successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "url": "https://example.com/webhooks/coinbax",
    "eventTypes": [
      "transaction.created",
      "transaction.completed",
      "transaction.failed"
    ],
    "secret": "string",
    "isActive": true,
    "ipWhitelist": [
      "192.168.1.1",
      "10.0.0.0/8"
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get webhook subscription

`GET /workspaces/{id}/webhooks/{webhookId}`

- Auth: Bearer token
- Operation ID: `getWorkspaceWebhook`

Get details of a specific webhook subscription.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Webhook subscription retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "url": "https://example.com/webhooks/coinbax",
    "eventTypes": [
      "transaction.created",
      "transaction.completed",
      "transaction.failed"
    ],
    "secret": "string",
    "isActive": true,
    "ipWhitelist": [
      "192.168.1.1",
      "10.0.0.0/8"
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Delete webhook subscription

`DELETE /workspaces/{id}/webhooks/{webhookId}`

- Auth: Bearer token
- Operation ID: `deleteWorkspaceWebhook`

Delete a webhook subscription.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Example request

```bash
curl -X DELETE https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId> \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Webhook subscription deleted successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "message": "Subscription deleted"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Update webhook subscription

`PATCH /workspaces/{id}/webhooks/{webhookId}`

- Auth: Bearer token
- Operation ID: `updateWorkspaceWebhook`

Update a webhook subscription.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | string (uri) | no |  |
| `eventTypes` | array of string | no |  |
| `isActive` | boolean | no |  |
| `ipWhitelist` | array of string | no |  |
| `metadata` | object | no |  |

```json
{
  "url": "https://example.com",
  "eventTypes": [
    "string"
  ],
  "isActive": true,
  "ipWhitelist": [
    "string"
  ],
  "metadata": {}
}
```

### Example request

```bash
curl -X PATCH https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId> \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com",
  "eventTypes": [
    "string"
  ],
  "isActive": true,
  "ipWhitelist": [
    "string"
  ],
  "metadata": {}
}'
```

### Responses

**200** Webhook subscription updated successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "platformId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
    "url": "https://example.com/webhooks/coinbax",
    "eventTypes": [
      "transaction.created",
      "transaction.completed",
      "transaction.failed"
    ],
    "secret": "string",
    "isActive": true,
    "ipWhitelist": [
      "192.168.1.1",
      "10.0.0.0/8"
    ],
    "metadata": {},
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
}
```

**400** Bad request - validation error

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Get webhook delivery logs

`GET /workspaces/{id}/webhooks/{webhookId}/delivery-logs`

- Auth: Bearer token
- Operation ID: `getWorkspaceWebhookDeliveryLogs`

Get delivery logs for a webhook subscription.

**Requires:** Workspace access

Logs are retained for 30 days. Useful for debugging delivery issues.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |
| `limit` | query | integer | no | Number of logs to return (default 20) |
| `offset` | query | integer | no | Offset for pagination |
| `successOnly` | query | boolean | no | Only return successful deliveries |
| `failuresOnly` | query | boolean | no | Only return failed deliveries |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId>/delivery-logs \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Delivery logs retrieved successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "logs": [
      {
        "id": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "webhookSubscriptionId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "eventType": "transaction.created",
        "eventId": "9f8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
        "deliveryAttempt": 1,
        "success": true,
        "statusCode": 200,
        "responseTime": 150,
        "errorMessage": "string",
        "requestHeaders": {},
        "responseBody": "string",
        "createdAt": "2026-01-15T12:00:00.000Z"
      }
    ],
    "total": 150
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Initiate secret rotation

`POST /workspaces/{id}/webhooks/{webhookId}/rotate-secret`

- Auth: Bearer token
- Operation ID: `rotateWorkspaceWebhookSecret`

Start the secret rotation process for a webhook.

**Requires:** Workspace access

**Zero-Downtime Rotation:**
1. Call this endpoint to get a new secret
2. Update your webhook handler to accept both old and new secrets
3. Call `/complete-rotation` to finalize

The old secret remains valid until rotation is completed.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId>/rotate-secret \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Secret rotation initiated

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "newSecret": "whsec_newABC123...",
    "rotationExpiresAt": "2026-02-27T12:00:00Z"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Complete secret rotation

`POST /workspaces/{id}/webhooks/{webhookId}/complete-rotation`

- Auth: Bearer token
- Operation ID: `completeWorkspaceWebhookRotation`

Complete the secret rotation process.

**Requires:** Workspace access

After calling this, only the new secret will be valid.
Make sure your webhook handler has been updated first.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId>/complete-rotation \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Secret rotation completed

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "message": "Secret rotation completed successfully"
  }
}
```

**400** No active rotation in progress

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Reset circuit breaker

`POST /workspaces/{id}/webhooks/{webhookId}/reset-circuit-breaker`

- Auth: Bearer token
- Operation ID: `resetWorkspaceWebhookCircuitBreaker`

Reset the circuit breaker for a webhook subscription.

**Requires:** Workspace access

**Circuit Breaker States:**
- **CLOSED:** Normal operation
- **OPEN:** Delivery paused (too many failures)
- **HALF_OPEN:** Testing recovery

Use this to manually reset after fixing endpoint issues.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId>/reset-circuit-breaker \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Circuit breaker reset successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "circuitBreakerState": "CLOSED",
    "message": "Circuit breaker reset to CLOSED"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## Test webhook endpoint

`POST /workspaces/{id}/webhooks/{webhookId}/test`

- Auth: Bearer token
- Operation ID: `testWorkspaceWebhook`

Send a test event to the webhook endpoint.

**Requires:** Workspace access

Useful for verifying your endpoint is correctly configured
and can receive events.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |
| `webhookId` | path | string (uuid) | yes | Webhook subscription ID |

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/<webhookId>/test \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Test event sent

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "success": true,
    "statusCode": 200,
    "responseTime": 150,
    "error": "string"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error

---

## List webhook event types

`GET /workspaces/{id}/webhooks/events/types`

- Auth: Bearer token
- Operation ID: `listWorkspaceWebhookEventTypes`

Get all available webhook event types that can be subscribed to.

**Requires:** Workspace access

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string (uuid) | yes | Workspace ID |

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/workspaces/<id>/webhooks/events/types \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Event types retrieved successfully

```json
{
  "success": true,
  "data": {
    "eventTypes": [
      {
        "type": "transaction.created",
        "description": "A new transaction was created",
        "category": "transactions"
      },
      {
        "type": "transaction.completed",
        "description": "A transaction was completed",
        "category": "transactions"
      },
      {
        "type": "dispute.created",
        "description": "A dispute was opened",
        "category": "disputes"
      }
    ]
  },
  "meta": {
    "timestamp": "2026-02-26T12:00:00Z",
    "requestId": "req_abc123"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**404** Resource not found

**500** Internal server error