> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talview.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Unsubscribing from Webhooks

> How to disable existing webhook subscriptions safely via the Graph API.

## Overview

When an endpoint is deprecated, compromised, or temporarily offline, you can disable its deliveries by calling the `hook_unsubscribe` Graph action. The action requires the subscription's UUID, which is returned whenever you create or list subscriptions. Tenant and platform administrators can perform this operation; other roles are denied.

## Unsubscription Workflow

1. **Identify the subscription** – retrieve the `uuid` from your records.
2. **Call `hook_unsubscribe`** – send the Graph mutation with the `uuid` payload.
3. **Confirm the response** – inspect the returned `Hook_Subscribe_Output` to verify the intended subscription was disabled.

### Unsubsribing API Inputs

`hook_unsubscribe` expects a single field:

* **uuid**: String

```typescript theme={null}
type UnsubscribeInput = {
  uuid: string; // must be a valid UUIDv4
};
```

### Unsubscibing Payload Response Shape

The action mirrors the subscribe response so you can confirm which event and endpoint were affected.

```typescript theme={null}
type UnsubscribeResult = {
  id: number;
  uuid: string;
  is_enabled: boolean;
  event_type: {
    id: number;
    name: string;
    verb: string;
    resource_type: string;
    service: string;
    schema: Record<string, unknown> | null;
  };
};
```

### Unsubscribing Response Example

The action returns the now-unsubcribed subscription, including its unique identifiers and the event metadata snapshot

```JSON theme={null}
{
  "data": {
    "hook_unsubscribe": {
      "id": 4,
      "uuid": "848ef0a7-af58-49de-bfea-7830fac8b0e0",
      "is_enabled": false,
      "event_type": {
        "id": 10,
        "name": "session.instance.created",
        "verb": null,
        "resource_type": null,
        "service": null,
        "schema": null
      }
    }
  }
}
```

## Mutation Example

Use the mutation below with admin credentials. The mutation simply forwards the `uuid` variable to the action.

```graphql theme={null}
mutation HookUnsubscribe($uuid: uuid!) {
  hook_unsubscribe(uuid: $uuid) {
    id
    uuid
    is_enabled
    event_type {
      name
      service
      resource_type
      verb
    }
  }
}
```

Example variables:

```json theme={null}
{
  "uuid": "a97e2443-cffb-4eb3-bcb4-0f1210865d45"
}
```

## Managing the Lifecycle

* **Bulk clean-up**: Iterate through stored UUIDs in automation to remove multiple endpoints; rate limits apply per Graph API policy.
* **Rollback/Resubscribe**: If you unsubscribed by mistake, call `hook_subscribe` again with the same event type and endpoint—new IDs will be issued.
* **Auditing**: Keep the unsubscribe response and mutation request ID for compliance logs; the `created_at`/`updated_at` values remain available via the subscription tables even after disabling.

## Testing & Verification

* After unsubscribing, trigger the original event to confirm your endpoint no longer receives calls.
* Monitor delivery logs; you should see a “disabled target” status associated with the `uuid`.
* In staging, create a fresh subscription, unsubscribe it, and ensure automation handles both states before promoting to production.

## Troubleshooting

* **Unknown UUID**: `422 Unprocessable Entity` indicates the UUID is missing or malformed; validate the identifier format and ensure it exists.
* **Permission denied**: use a token scoped to `TENANT_ADMIN` or `PLATFORM_ADMIN`.
* **Race conditions**: if events arrive between creating a new subscription and unsubscribing the old one, design idempotent consumers to handle duplicate deliveries.
* **Record not found**: the backend returns a not-found error if the subscription was already removed—safe to ignore if you intended a no-op.

## Related Resources

* `docs/graph-api-reference/webhooks/subscribing.mdx` – how to onboard endpoints and capture subscription UUIDs.
* `docs/graph-api-reference/webhooks/overview.mdx` – retry semantics and event catalog.