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

# Webhooks SDK Reference

> SDK reference for the Webhooks API, available in Node.js and Python.

## Webhooks

### List Webhooks

Returns a page of webhooks in the current workspace. By default, the first 20 matching webhooks are ordered by creation time, newest first. Supplied filters are combined, `count` reports the total number of matches before pagination, and `has_more` indicates whether another page is available.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.webhooks.list()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.webhooks.list();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "page": Optional[int],
        "limit": Optional[int],
        "search": Optional[str],
        "event": Optional[str],
        "sort": Optional[str],
        "direction": Optional[str],
        "content_type": Optional[str],
        "enabled": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      page?: number;
      limit?: number;
      search?: string;
      event?: string;
      sort?: string;
      direction?: string;
      contentType?: string;
      enabled?: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "count": int,
        "items": [{
            "id": str,
            "url": str,
            "content_type": Literal["application/json", "application/x-www-form-urlencoded"],
            "display_name": str,
            "events": List[str],
            "secret": str,
            "enabled": Optional[bool],
            "failure_count": Optional[int],
            "created_by_id": str,
            "updated_by_id": str,
            "created": date,
            "updated": date,
        }],
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      count: number;
      items: {
        id: string;
        url: string;
        contentType: "application/json" | "application/x-www-form-urlencoded";
        displayName: string;
        events: string[];
        secret: string;
        enabled?: boolean;
        failureCount?: number;
        createdById: string;
        updatedById: string;
        created: Date;
        updated: Date;
      }[];
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Create a Webhook

Creates a webhook that delivers the selected workspace events to an HTTPS endpoint. Generate a signing secret first with `GET /v2/webhooks/secret`.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.webhooks.create(id="<id>", url="https://outlying-tenement.name/", content_type="application/json", display_name="June.Hand", events=[
          "<value 1>",
          "<value 2>",
      ], secret="<value>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.webhooks.create({
      id: "<id>",
      url: "https://outlying-tenement.name/",
      contentType: "application/json",
      displayName: "June.Hand",
      events: [
        "<value 1>",
        "<value 2>",
      ],
      secret: "<value>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,  # required
        "url": str,  # required
        "content_type": Literal["application/json", "application/x-www-form-urlencoded"],  # required
        "display_name": str,  # required
        "events": List[str],  # required
        "secret": str,  # required
        "enabled": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;  // required
      url: string;  // required
      contentType: "application/json" | "application/x-www-form-urlencoded";  // required
      displayName: string;  // required
      events: string[];  // required
      secret: string;  // required
      enabled?: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "url": str,
        "content_type": Literal["application/json", "application/x-www-form-urlencoded"],
        "display_name": str,
        "events": List[str],
        "secret": str,
        "enabled": Optional[bool],
        "failure_count": Optional[int],
        "created_by_id": str,
        "updated_by_id": str,
        "created": date,
        "updated": date,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      url: string;
      contentType: "application/json" | "application/x-www-form-urlencoded";
      displayName: string;
      events: string[];
      secret: string;
      enabled?: boolean;
      failureCount?: number;
      createdById: string;
      updatedById: string;
      created: Date;
      updated: Date;
    }
    ```
  </CodeGroup>
</Expandable>

### Count Webhooks

Returns the total number of enabled and disabled webhooks in the current workspace.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.webhooks.count()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.webhooks.count();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "total": int,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      total: number;
    }
    ```
  </CodeGroup>
</Expandable>

### Query Webhooks <Badge color="yellow" size="lg" stroke>\[deprecated]</Badge>

**Deprecated.** Returns webhooks matching legacy query filters. Use `GET /v2/webhooks` for pagination, search, event filtering, and sorting.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.webhooks.query()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.webhooks.query({});

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "pagination": {  # optional
            "page": Optional[int],
            "limit": Optional[int],
            "last_id": Optional[str],
            "first_id": Optional[str],
        },
        "sorting_props": [{  # optional
            "key": Optional[str],
            "direction": Optional[str],
        }],
        "query": Dict[str, Any],  # optional
        "filters": Dict[str, Any],  # optional
        "included_fields": Dict[str, str],  # optional
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      pagination?: {
        page?: number;
        limit?: number;
        lastId?: string;
        firstId?: string;
      };
      sortingProps?: {
        key?: string;
        direction?: string;
      }[];
      query?: Record<string, unknown>;
      filters?: Record<string, unknown>;
      includedFields?: Record<string, string>;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "count": int,
        "items": [{
            "id": str,
            "url": str,
            "content_type": Literal["application/json", "application/x-www-form-urlencoded"],
            "display_name": str,
            "events": List[str],
            "secret": str,
            "enabled": Optional[bool],
            "failure_count": Optional[int],
            "created_by_id": str,
            "updated_by_id": str,
            "created": date,
            "updated": date,
        }],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      count: number;
      items: {
        id: string;
        url: string;
        contentType: "application/json" | "application/x-www-form-urlencoded";
        displayName: string;
        events: string[];
        secret: string;
        enabled?: boolean;
        failureCount?: number;
        createdById: string;
        updatedById: string;
        created: Date;
        updated: Date;
      }[];
    }
    ```
  </CodeGroup>
</Expandable>

### Generate Secret

Generates a signing secret for verifying webhook deliveries. The secret is not persisted until it is used to create or update a webhook; store it securely.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.webhooks.generate_secret()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.webhooks.generateSecret();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "secret": str,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      secret: string;
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a Webhook

Retrieves a webhook in the current workspace by ID. The response includes its signing secret; treat it as sensitive.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.webhooks.get(id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.webhooks.get({
      id: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "url": str,
        "content_type": Literal["application/json", "application/x-www-form-urlencoded"],
        "display_name": str,
        "events": List[str],
        "secret": str,
        "enabled": Optional[bool],
        "failure_count": Optional[int],
        "created_by_id": str,
        "updated_by_id": str,
        "created": date,
        "updated": date,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      url: string;
      contentType: "application/json" | "application/x-www-form-urlencoded";
      displayName: string;
      events: string[];
      secret: string;
      enabled?: boolean;
      failureCount?: number;
      createdById: string;
      updatedById: string;
      created: Date;
      updated: Date;
    }
    ```
  </CodeGroup>
</Expandable>

### Delete a Webhook

Deletes a webhook in the current workspace and returns the deleted webhook ID.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.webhooks.delete(id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.webhooks.delete({
      id: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
    }
    ```
  </CodeGroup>
</Expandable>

### Update a Webhook

Updates the supplied fields on a webhook in the current workspace. Omitted fields are unchanged. The response contains the applied fields rather than the complete webhook.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.webhooks.update(id="<id>", request_body={})

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.webhooks.update({
      id: "<id>",
      requestBody: {},
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,  # required
        "request_body": Dict[str, Any],  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;  // required
      requestBody: Record<string, unknown>;  // required
    }
    ```
  </CodeGroup>
</Expandable>