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

# List webhooks

> Retrieve all webhook endpoints registered to your account

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

<Callout icon="circle-check" color="#16a34a">
  **Free** - does not consume credits
</Callout>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://xquik.com/api/v1/webhooks \
    -H "x-api-key: xq_YOUR_KEY_HERE" \
    | jq '.webhooks[] | {
      webhook_id: .id,
      url,
      event_types: .eventTypes,
      is_active: .isActive,
      delivery_status: .deliveryStatus,
      consecutive_failures: .consecutiveFailures,
      failure_hard_cap: .failureHardCap,
      created_at: .createdAt,
      update_endpoint: ("/api/v1/webhooks/" + .id),
      delete_endpoint: ("/api/v1/webhooks/" + .id),
      test_endpoint: ("/api/v1/webhooks/" + .id + "/test"),
      resume_endpoint: ("/api/v1/webhooks/" + .id + "/resume"),
      deliveries_endpoint: ("/api/v1/webhooks/" + .id + "/deliveries"),
      signing_secret_available: false
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://xquik.com/api/v1/webhooks", {
    headers: { "x-api-key": "xq_YOUR_KEY_HERE" },
  });
  const data = await response.json();
  const webhookRows = data.webhooks.map((webhook) => ({
    webhook_id: webhook.id,
    url: webhook.url,
    event_types: webhook.eventTypes,
    is_active: webhook.isActive,
    delivery_status: webhook.deliveryStatus,
    consecutive_failures: webhook.consecutiveFailures,
    failure_hard_cap: webhook.failureHardCap,
    created_at: webhook.createdAt,
    update_endpoint: `/api/v1/webhooks/${webhook.id}`,
    delete_endpoint: `/api/v1/webhooks/${webhook.id}`,
    test_endpoint: `/api/v1/webhooks/${webhook.id}/test`,
    resume_endpoint: `/api/v1/webhooks/${webhook.id}/resume`,
    deliveries_endpoint: `/api/v1/webhooks/${webhook.id}/deliveries`,
    signing_secret_available: false,
  }));

  for (const row of webhookRows) {
    process.stdout.write(`${JSON.stringify(row)}\n`);
  }
  ```

  ```python Python theme={null}
  import json
  import requests

  response = requests.get(
      "https://xquik.com/api/v1/webhooks",
      headers={"x-api-key": "xq_YOUR_KEY_HERE"},
  )
  data = response.json()
  webhook_rows = [
      {
          "webhook_id": webhook["id"],
          "url": webhook["url"],
          "event_types": webhook["eventTypes"],
          "is_active": webhook["isActive"],
          "delivery_status": webhook["deliveryStatus"],
          "consecutive_failures": webhook["consecutiveFailures"],
          "failure_hard_cap": webhook["failureHardCap"],
          "created_at": webhook["createdAt"],
          "update_endpoint": f"/api/v1/webhooks/{webhook['id']}",
          "delete_endpoint": f"/api/v1/webhooks/{webhook['id']}",
          "test_endpoint": f"/api/v1/webhooks/{webhook['id']}/test",
          "resume_endpoint": f"/api/v1/webhooks/{webhook['id']}/resume",
          "deliveries_endpoint": f"/api/v1/webhooks/{webhook['id']}/deliveries",
          "signing_secret_available": False,
      }
      for webhook in data["webhooks"]
  ]
  for row in webhook_rows:
      print(json.dumps(row))
  ```

  ```go Go theme={null}
  package main

  import (
    "encoding/json"
    "log"
    "net/http"
    "os"
  )

  type Webhook struct {
    ConsecutiveFailures int      `json:"consecutiveFailures"`
    CreatedAt           string   `json:"createdAt"`
    DeliveryStatus      string   `json:"deliveryStatus"`
    EventTypes          []string `json:"eventTypes"`
    FailureHardCap      int      `json:"failureHardCap"`
    ID                  string   `json:"id"`
    IsActive            bool     `json:"isActive"`
    URL                 string   `json:"url"`
  }

  type WebhookResponse struct {
    Webhooks []Webhook `json:"webhooks"`
  }

  type WebhookRow struct {
    WebhookID              string   `json:"webhook_id"`
    URL                    string   `json:"url"`
    EventTypes             []string `json:"event_types"`
    IsActive               bool     `json:"is_active"`
    DeliveryStatus         string   `json:"delivery_status"`
    ConsecutiveFailures    int      `json:"consecutive_failures"`
    FailureHardCap         int      `json:"failure_hard_cap"`
    CreatedAt              string   `json:"created_at"`
    UpdateEndpoint         string   `json:"update_endpoint"`
    DeleteEndpoint         string   `json:"delete_endpoint"`
    TestEndpoint           string   `json:"test_endpoint"`
    ResumeEndpoint         string   `json:"resume_endpoint"`
    DeliveriesEndpoint     string   `json:"deliveries_endpoint"`
    SigningSecretAvailable bool     `json:"signing_secret_available"`
  }

  func main() {
    req, err := http.NewRequest("GET", "https://xquik.com/api/v1/webhooks", nil)
    if err != nil {
      log.Fatal(err)
    }
    req.Header.Set("x-api-key", "xq_YOUR_KEY_HERE")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
      log.Fatal(err)
    }
    defer resp.Body.Close()

    var data WebhookResponse
    if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
      log.Fatal(err)
    }

    encoder := json.NewEncoder(os.Stdout)
    for _, webhook := range data.Webhooks {
      row := WebhookRow{
        WebhookID:              webhook.ID,
        URL:                    webhook.URL,
        EventTypes:             webhook.EventTypes,
        IsActive:               webhook.IsActive,
        DeliveryStatus:         webhook.DeliveryStatus,
        ConsecutiveFailures:    webhook.ConsecutiveFailures,
        FailureHardCap:         webhook.FailureHardCap,
        CreatedAt:              webhook.CreatedAt,
        UpdateEndpoint:         "/api/v1/webhooks/" + webhook.ID,
        DeleteEndpoint:         "/api/v1/webhooks/" + webhook.ID,
        TestEndpoint:           "/api/v1/webhooks/" + webhook.ID + "/test",
        ResumeEndpoint:         "/api/v1/webhooks/" + webhook.ID + "/resume",
        DeliveriesEndpoint:     "/api/v1/webhooks/" + webhook.ID + "/deliveries",
        SigningSecretAvailable: false,
      }
      if err := encoder.Encode(row); err != nil {
        log.Fatal(err)
      }
    }
  }
  ```
</CodeGroup>

These examples shape one inventory row per webhook instead of printing the full
response page. Split the rows by `is_active` and `delivery_status`, then store
update, delete, test, resume, and delivery-log endpoints with each receiver.
List responses never include the signing secret; keep the one-time `secret` from
[Create Webhook](/api-reference/webhooks/create) in your secret manager.

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key. Session cookie authentication is also supported.
</ParamField>

## Response

<Tabs>
  <Tab title="200 OK">
    <ResponseField name="webhooks" type="array">
      List of webhook objects for your account. Returns up to 200 webhooks.

      <Expandable title="webhook object">
        <ResponseField name="id" type="string">
          Unique webhook identifier.
        </ResponseField>

        <ResponseField name="url" type="string">
          Delivery endpoint URL.
        </ResponseField>

        <ResponseField name="eventTypes" type="string[]">
          Event types this webhook is subscribed to.
        </ResponseField>

        <ResponseField name="isActive" type="boolean">
          Whether the webhook is currently active.
        </ResponseField>

        <ResponseField name="consecutiveFailures" type="number">
          Consecutive delivery failures recorded for this webhook.
        </ResponseField>

        <ResponseField name="deliveryStatus" type="string">
          `active`, `paused`, or `needs_attention`.
        </ResponseField>

        <ResponseField name="failureHardCap" type="number">
          Failure count where the webhook needs attention before resuming.
        </ResponseField>

        <ResponseField name="createdAt" type="string">
          ISO 8601 creation timestamp.
        </ResponseField>
      </Expandable>
    </ResponseField>

    ```json theme={null}
    {
      "webhooks": [
        {
          "id": "15",
          "url": "https://your-server.com/webhook",
          "eventTypes": ["tweet.new", "tweet.reply"],
          "isActive": true,
          "consecutiveFailures": 0,
          "deliveryStatus": "active",
          "failureHardCap": 200,
          "createdAt": "2026-02-24T10:30:00.000Z"
        },
        {
          "id": "16",
          "url": "https://backup.example.com/xquik",
          "eventTypes": ["tweet.new"],
          "isActive": false,
          "consecutiveFailures": 200,
          "deliveryStatus": "needs_attention",
          "failureHardCap": 200,
          "createdAt": "2026-02-20T08:15:00.000Z"
        }
      ]
    }
    ```

    The `secret` is **never** included in list responses. It is only returned once at creation time.
  </Tab>

  <Tab title="401 Unauthenticated">
    ```json theme={null}
    { "error": "unauthenticated" }
    ```

    Missing or invalid API key / session cookie.
  </Tab>

  <Tab title="429 Rate Limited">
    ```json theme={null}
    { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 1 }
    ```

    Too many requests. Wait for the `Retry-After` header before retrying.
  </Tab>
</Tabs>

## Inventory handoff

Use this endpoint when an ops job, CRM integration, alert worker, or agent needs
to reconcile which signed webhook endpoints are configured for the account.

<CardGroup cols={2}>
  <Card title="Configuration ID" icon="fingerprint">
    Store `webhooks[].id` for updates, deletes, test deliveries, and delivery
    history lookups.
  </Card>

  <Card title="Delivery Target" icon="link">
    Store `webhooks[].url` so configuration reviews can detect stale receiver
    endpoints before production monitor events fail.
  </Card>

  <Card title="Event Filter" icon="funnel">
    Store `webhooks[].eventTypes` and compare it with monitor event types before
    expecting `tweet.new`, `tweet.quote`, `tweet.reply`, or `tweet.retweet`.
  </Card>

  <Card title="Active State" icon="toggle-right">
    Store `webhooks[].isActive`; inactive webhooks do not receive monitor
    events. Use `deliveryStatus` to distinguish paused from needs-attention
    receivers.
  </Card>

  <Card title="Delivery Status" icon="radio">
    Store `webhooks[].deliveryStatus`. Route `needs_attention` rows to
    [Resume Webhook](/api-reference/webhooks/resume) after the receiver is fixed.
  </Card>

  <Card title="Failure Counter" icon="activity">
    Store `webhooks[].consecutiveFailures` and `webhooks[].failureHardCap` for
    alerting before the receiver reaches the recovery gate.
  </Card>

  <Card title="Change Links" icon="route">
    For each row, link active receivers to
    [Update Webhook](/api-reference/webhooks/update), [Test Webhook](/api-reference/webhooks/test),
    [Resume Webhook](/api-reference/webhooks/resume), and
    [List Deliveries](/api-reference/webhooks/deliveries). Link stale receivers
    to [Delete Webhook](/api-reference/webhooks/delete).
  </Card>

  <Card title="Inactive Review" icon="toggle-left">
    Inactive rows are configuration records, not active delivery targets. Keep
    their `webhooks[].id` so deactivation receipts and rollback plans can find
    the same webhook.
  </Card>

  <Card title="Delivery Audit" icon="activity">
    Use the per-webhook deliveries endpoint to store `streamEventId`, `status`,
    `attempts`, `lastStatusCode`, `lastError`, `createdAt`, and `deliveredAt`.
  </Card>

  <Card title="Event Join" icon="link">
    Use delivery `streamEventId` as the `{id}` for
    [Get Event](/api-reference/events/get). Store `monitorId`, `monitorType`,
    `type`, `occurredAt`, and `data` with the inventory audit.
  </Card>

  <Card title="Created At" icon="calendar-clock">
    Store `webhooks[].createdAt` for audit logs and configuration drift checks.
  </Card>

  <Card title="Signing Secret" icon="shield-check">
    The signing `secret` is not listed. Store it from
    [Create Webhook](/api-reference/webhooks/create), then verify deliveries
    with [Signature Verification](/webhooks/verification).
  </Card>
</CardGroup>

<Note>
  This endpoint supports **dual authentication**: API key (`x-api-key` header) or session cookie from the dashboard.

  **Next steps:** [Create Webhook](/api-reference/webhooks/create) · [Update Webhook](/api-reference/webhooks/update) · [Test Webhook](/api-reference/webhooks/test) · [Resume Webhook](/api-reference/webhooks/resume) · [List Deliveries](/api-reference/webhooks/deliveries) · [Get Event](/api-reference/events/get) · [Delete Webhook](/api-reference/webhooks/delete)
</Note>