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

# Webhooks

> Create and manage webhooks and event subscriptions for prompts and evaluators using the Arize TypeScript SDK.

<Note>
  The `webhooks` functions are currently in **ALPHA**. The API may change without notice. A one-time warning is emitted on first use.
</Note>

Webhooks are organization-owned destinations that receive event deliveries over HTTPS. Credentials are write-only: `authToken` and custom header values are never returned, and the HMAC signing secret is returned once, in the create response.

## List Webhooks

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { listWebhooks } from "@arizeai/ax-client";

const { data: webhooks, pagination } = await listWebhooks({
  organization: "my-org",  // organization name or ID (optional)
  name: "deploy",          // case-insensitive substring filter on name (optional)
  limit: 10,
});
```

## Create a Webhook

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { createWebhook } from "@arizeai/ax-client";

const webhook = await createWebhook({
  organization: "my-org",  // organization name or ID
  name: "Deploy Notifications",
  url: "https://example.com/hooks/arize",
  description: "Notifies our deploy pipeline",  // optional
  authType: "HMAC_SHA256",  // "BEARER" (default) or "HMAC_SHA256"; cannot be changed after creation
  authToken: "Bearer my-token",  // optional; only valid when authType is BEARER
  timeoutMs: 30000,  // optional, 1000-60000, defaults to 30000
  headers: { "X-Custom": "value" },  // optional custom headers, at most 20
});

// For HMAC_SHA256 webhooks, the signing secret is returned once:
console.log(webhook.signingSecret);
```

Returns a `CreatedWebhook`. The `signingSecret` field is present only for `HMAC_SHA256` webhooks and only in this response — it cannot be retrieved again.

## Get a Webhook

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { getWebhook } from "@arizeai/ax-client";

const webhook = await getWebhook({
  webhook: "Deploy Notifications",  // webhook name or ID
  organization: "my-org",           // required when resolving by webhook name
});
```

## Update a Webhook

Omitted fields keep their current value. At least one field must be provided.

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { updateWebhook } from "@arizeai/ax-client";

const updated = await updateWebhook({
  webhook: "Deploy Notifications",  // webhook name or ID
  organization: "my-org",           // required when resolving by webhook name
  name: "Deploy Notifications v2",  // optional
  description: null,                // optional; pass null to clear
  url: "https://example.com/hooks/v2",  // optional
  authToken: "Bearer new-token",    // optional; BEARER webhooks only
  timeoutMs: 45000,                 // optional, 1000-60000
  headers: { "X-Custom": "value" }, // optional; replaces the whole header map
});
```

## Delete a Webhook

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { deleteWebhook } from "@arizeai/ax-client";

await deleteWebhook({
  webhook: "Deploy Notifications",  // webhook name or ID
  organization: "my-org",           // required when resolving by webhook name
});
```

## Test a Webhook

Sends a test delivery to the webhook's endpoint and reports the outcome.

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { testWebhook } from "@arizeai/ax-client";

const result = await testWebhook({
  webhook: "Deploy Notifications",  // webhook name or ID
  organization: "my-org",           // required when resolving by webhook name
});
```

Returns a `TestWebhookResponse` with `statusCode` (`number`, `502` when no response was received) and `errorMessage` (`string | null`, `null` on success).

## List Delivery Attempts

List the delivery attempts for a webhook, newest first.

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { listWebhookDeliveryAttempts } from "@arizeai/ax-client";

const { data: attempts, pagination } = await listWebhookDeliveryAttempts({
  webhook: "Deploy Notifications",  // webhook name or ID
  organization: "my-org",           // required when resolving by webhook name
  limit: 50,                        // optional, up to 500
});
```

## Manage Subscriptions

A subscription delivers one event from one prompt or evaluator to one webhook.

### List Subscriptions

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { listWebhookSubscriptions } from "@arizeai/ax-client";

const { data: subscriptions, pagination } = await listWebhookSubscriptions({
  sourceType: "PROMPT",         // optional; "PROMPT" or "EVALUATOR". Requires sourceId
  sourceId: "your_prompt_id",   // optional; requires sourceType
  limit: 10,
});
```

### Create a Subscription

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { createWebhookSubscription } from "@arizeai/ax-client";

const subscription = await createWebhookSubscription({
  webhook: "Deploy Notifications",  // webhook name or ID
  organization: "my-org",           // required when resolving by webhook name
  sourceType: "PROMPT",             // "PROMPT" or "EVALUATOR"
  sourceId: "your_prompt_id",       // ID of the prompt or evaluator
  event: "PROMPT_VERSION_CREATED",  // must belong to sourceType
});
```

### Get a Subscription

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { getWebhookSubscription } from "@arizeai/ax-client";

const subscription = await getWebhookSubscription({
  subscriptionId: "your_subscription_id",
});
```

### Delete a Subscription

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { deleteWebhookSubscription } from "@arizeai/ax-client";

await deleteWebhookSubscription({
  subscriptionId: "your_subscription_id",
});
```