---
id: webhooks-query
slug: /apis/webhooks/query
title: 'Query Subscriptions'
description: 'List webhook subscriptions with paging, or retrieve one by id.'
sidebar_label: 'Query'
sidebar_position: 5
tags: ['api', 'webhooks', 'query']
---

## List Subscriptions

```text
GET ~/api/webhook?page=pageSize,pageStart
```

| Parameter | In    | Required | Description                                                              |
| --------- | ----- | -------- | ------------------------------------------------------------------------ |
| `page`    | query | no       | `pageSize,pageStart` — **size first, then start**. Defaults to `25,0`.    |

:::warning Size comes first
The `page` parameter is a comma-separated pair in the order **size, start** — `page=10,20`
means "10 per page, starting at offset 20", not "page 10 of size 20". Both values must be
present for either to take effect; a single value is ignored and the defaults apply.
:::

```bash title="Request"
curl "https://{host}/{instance}/api/webhook?page=25,0" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/json"
```

### Response

```json title="200 OK"
{
  "total": 1,
  "pageSize": 25,
  "pageStart": 0,
  "_type": "WebhookSubscription",
  "results": [
    {
      "id": "336d997f-d9fa-4612-80e8-9f41a4b41352",
      "webhookId": "Webhook identifier",
      "url": "https://matchedUrl.com",
      "description": "Short description of the webhook subscription",
      "enabled": true,
      "eventTypes": [],
      "lastResponseAt": "0001-01-01T00:00:00Z",
      "retryCount": 0,
      "createdAt": "2018-09-27T20:28:41.3829451Z",
      "updatedAt": "2018-09-27T20:28:41.3829451Z",
      "createdBy": "Member:20"
    }
  ]
}
```

| Field       | Description                                             |
| ----------- | ------------------------------------------------------- |
| `total`     | Total subscriptions, not the number in this page.        |
| `pageSize`  | The effective page size.                                 |
| `pageStart` | The effective offset.                                    |
| `_type`     | Always `WebhookSubscription`.                            |
| `results`   | The subscriptions in this page.                          |

Page through by advancing `pageStart` by `pageSize` until you have seen `total` results.

## Retrieve One Subscription

```text
GET ~/api/webhook/:id
```

Where `:id` is the **server-assigned UUID** from
[create](/apis/webhooks/create#response), not your `webhookId`.

```bash title="Request"
curl "https://{host}/{instance}/api/webhook/336d997f-d9fa-4612-80e8-9f41a4b41352" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/json"
```

The response is a single subscription object, in the same shape as one `results` entry above.

An unknown id returns `404` with an explanatory body:

```json title="404 Not Found"
{
  "errorMessage": "Webhook subscription with id 336d997f-d9fa-4612-80e8-9f41a4b41352 was not found"
}
```

:::note Undocumented in the original reference
`GET ~/api/webhook/:id` did not appear in the published reference material at all.
:::

## Fields Worth Watching

Two fields make this endpoint the first place to look when a webhook has "stopped working":

- **`retryCount`** — consecutive failed deliveries. Non-zero means deliveries are failing right
  now. When it reaches the instance's retry limit (default `5`), the subscription is taken out
  of service.
- **`lastResponseAt`** — when a delivery attempt last got a response. Still
  `0001-01-01T00:00:00Z` after events should have fired means nothing has ever been delivered —
  suspect the event type definition or `enabled`, not the receiver.

For the detail behind those numbers, use [delivery status](/apis/webhooks/status).

## Notes

- `authorizationHeader` and `secret` are never returned by this endpoint. They are write-only.
- The list is **not** filtered to subscriptions you created; it is instance-wide, consistent
  with the `ManageConfig` privilege the API requires.
- Recover a lost `id` by listing and matching on your own `webhookId`.

## Related Topics

- [Create a subscription](/apis/webhooks/create)
- [Delivery status](/apis/webhooks/status)
- [Update a subscription](/apis/webhooks/update)