# Hooks API — Read

Use the read endpoints to retrieve webhook subscriptions for your account. You can list all subscriptions or retrieve a single one by ID.

---

## Endpoints

| Method | URL | Description |
|---|---|---|
| GET | `https://e1.envoke.com/v1/hooks.json` | Return all webhook subscriptions. |
| GET | `https://e1.envoke.com/v1/hooks/{ID}.json` | Return a single subscription. |

Authentication is via HTTP Basic Auth using your API ID and API Key.

---

## List Webhook Subscriptions

```
GET https://e1.envoke.com/v1/hooks.json
```

Returns a JSON array of all webhook subscriptions for your account. Unlike most Envoke list endpoints, **all subscriptions are returned by default** — there is no default limit. Most accounts have a small number of subscriptions, so pagination is rarely necessary.

### Query Parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `limit` | integer | *(none)* | Maximum number of results to return. When omitted, all subscriptions are returned. |
| `skip` | integer | `0` | Number of records to skip. Use with `limit` to paginate. |
| `fields` | string | *(all)* | Comma-separated list of fields to include in each result (e.g. `id,type,url`). |
| `type` | string | — | Filter results to subscriptions of the given event type (e.g. `?type=form_submission`). |

### Response

A JSON array of hook objects. Returns an empty array (`[]`) if no subscriptions exist.

```json
[
  {
    "id": "9f1c2a42baedb56c7e65b3eeaf1a8814",
    "type": "form_submission",
    "url": "https://crm.ridgeline.edu/webhooks/envoke/admissions",
    "filter": { "form_id": "abc123def456" }
  },
  {
    "id": "a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7",
    "type": "new_contact",
    "url": "https://sis.ridgeline.edu/webhooks/contacts",
    "filter": {}
  }
]
```

---

## Get a Single Subscription

```
GET https://e1.envoke.com/v1/hooks/{ID}.json
```

Returns a single webhook subscription object. Replace `{ID}` with the 32-character hex subscription ID.

If the ID is not found, the API returns `null`.

### Response

```json
{
  "id": "9f1c2a42baedb56c7e65b3eeaf1a8814",
  "type": "form_submission",
  "url": "https://crm.ridgeline.edu/webhooks/envoke/admissions",
  "filter": { "form_id": "abc123def456" }
}
```

---

## Examples

### List all subscriptions

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" "$BASE/v1/hooks.json"
```

### Filter by event type

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" "$BASE/v1/hooks.json?type=form_submission"
```

### Paginate (first 5, skip first 5)

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" "$BASE/v1/hooks.json?limit=5&skip=5"
```

### Return only `id` and `type` fields

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" "$BASE/v1/hooks.json?fields=id,type"
```

### Get a single subscription by ID

```bash
curl -X GET -gs -u "$API_ID:$API_KEY" \
  "$BASE/v1/hooks/9f1c2a42baedb56c7e65b3eeaf1a8814.json"
```

---

*Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.*

*Full reference, OpenAPI description, and Postman collection: [developers.envoke.com](https://developers.envoke.com).*