# Governance And Events

> API Kickstart for approvals, events, and webhook endpoints.

Source: https://business-api-docs.youhodler.com/docs/reference/governance-and-events

This group covers control and observation around execution. Read it in outcome
order: define governance before execution, inspect approval work when control
cases are created, and use events plus webhook delivery to observe what the
runtime actually did.

> **Why this group exists:** `policies`, `approvals`, and `action-tokens` govern execution. `events` and `webhook-endpoints` expose asynchronous visibility and delivery after the governed runtime has already started producing state changes.

> **Coming soon:** Of the operations on this page, `approvals` is exposed in /openapi.json with full schemas. `policies` have placeholder schemas in the spec and are callable on the deployed API. `webhook-endpoints` and `events` are callable in deployed environments but do not yet have OpenAPI path definitions — schemas are being prepared. `action-tokens` are not yet exposed.

## Control And Delivery

### Create policy

Governance definition. Create a policy when execution rules must be expressed through canonical control-plane resources instead of hidden tenant logic.

[API Reference: Create policy (POST)](/docs/api/reference/policies/policies-create)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/policies
```

**201 Created**

**400 Bad Request**

### List approvals

Pending decision work. List approvals when governed execution has created review cases and operators need the current queue of unresolved work.

[API Reference: List approvals (GET)](/docs/api/reference/approvals/approvals-list)

**Request URL — GET**
```http
GET https://business-api.youhodler.com/approvals?scope_ref=enterprises/11111111-1111-4111-8111-111111111111&status=pending
```
**200 OK**

```json
{
  "items": [
    {
      "action_family": "withdrawal",
      "created_at": "2026-05-01T10:00:00Z",
      "decision": null,
      "expires_at": "2026-05-01T10:00:00Z",
      "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "initiated_by": {
        "actor": null,
        "approved_by": null,
        "authenticated_principal": {
          "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "kind": "user",
          "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "enterprise_binding": {
          "tenant_type": "enterprise",
          "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        },
        "federation": null,
        "identity_source": "platform-managed",
        "initiated_by": null,
        "subject": {
          "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
          "kind": "user",
          "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
        }
      },
      "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "requirement_snapshot": {
        "authority_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "expires_at": "2026-05-01T10:00:00Z",
        "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
        "initiator_cannot_approve": true,
        "reason_code": "high_value",
        "required_human_approvals": 1,
        "requirement_key": "withdrawal_approval",
        "source": "policy"
      },
      "resource": "approval",
      "status": "pending",
      "updated_at": "2026-05-01T10:00:00Z"
    }
  ],
  "next_page_token": null
}
```

**400 Bad Request**

```json
{
  "code": "invalid_request",
  "message": "Invalid request payload."
}
```

### Approve approval

Explicit governance decision. Approve a pending approval when a governed operation should be released to continue through runtime execution.

[API Reference: Approve approval (POST)](/docs/api/reference/approvals/approvals-approve)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/approvals/apr_456/approve
```
**Request Body — application/json**
```json
{
  "reason": null
}
```
**200 Approval Approved**

```json
{
  "action_family": "withdrawal",
  "created_at": "2026-05-01T10:00:00Z",
  "decision": null,
  "expires_at": "2026-05-01T10:00:00Z",
  "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "initiated_by": {
    "actor": null,
    "approved_by": null,
    "authenticated_principal": {
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "kind": "user",
      "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "enterprise_binding": {
      "tenant_type": "enterprise",
      "topology_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    },
    "federation": null,
    "identity_source": "platform-managed",
    "initiated_by": null,
    "subject": {
      "id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
      "kind": "user",
      "tenant_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b"
    }
  },
  "operation_id": "b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
  "requirement_snapshot": {
    "authority_ref": "enterprises/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "expires_at": "2026-05-01T10:00:00Z",
    "governed_ref": "clients/b8e2f1a0-4c3d-4e5f-9a1b-2c3d4e5f6a7b",
    "initiator_cannot_approve": true,
    "reason_code": "high_value",
    "required_human_approvals": 1,
    "requirement_key": "withdrawal_approval",
    "source": "policy"
  },
  "resource": "approval",
  "status": "pending",
  "updated_at": "2026-05-01T10:00:00Z"
}
```

### List events

Replay-safe audit history. List events when an integration needs canonical lifecycle history, delayed reconciliation, or traceable replay after runtime changes.

[API Reference: List events (GET)](/docs/api)

**Request URL — GET**
```http
GET https://business-api.youhodler.com/events?aggregate_kind=withdrawal&page_size=20
```
**200 Event Page**

```json
{
  "items": [
    {
      "id": "evt_123",
      "event_type": "operation.withdrawal.executed.v1",
      "aggregate": {
        "kind": "withdrawal",
        "ref": "withdrawals/op_123"
      }
    }
  ],
  "next_page_token": null
}
```

### Create webhook endpoint

Push delivery target. Create a webhook endpoint when the tenant needs runtime state changes pushed into an external system instead of only pulled later from the event log.

[API Reference: Create webhook endpoint (POST)](/docs/api)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/webhook-endpoints
```
**Request Body — application/json**
```json
{
  "enterprise_id": "11111111-1111-4111-8111-111111111111",
  "url": "https://example.com/hooks/b2b2x",
  "event_types": [
    "operation.withdrawal.executed.v1"
  ],
  "secret": "replace-me"
}
```
**201 Webhook Created**

```json
{
  "id": "wh_123",
  "resource": "webhook-endpoint",
  "status": "disabled"
}
```

### Enable webhook endpoint

Delivery activation. Enable the webhook endpoint after configuration so new matching events begin flowing to the external target.

[API Reference: Enable webhook endpoint (POST)](/docs/api)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/webhook-endpoints/wh_123/enable
```
**200 Webhook Enabled**

```json
{
  "id": "wh_123",
  "resource": "webhook-endpoint",
  "status": "enabled"
}
```