Skip to main content

​
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
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. 
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 
{
  "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. 
mutation HookUnsubscribe($uuid: uuid!) {
  hook_unsubscribe(uuid: $uuid) {
    id
    uuid
    is_enabled
    event_type {
      name
      service
      resource_type
      verb
    }
  }
}
Example variables: 
{
  "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.
  • 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.