---
title: "List webhook subscriptions"
description: "Returns your webhook subscriptions, newest first, 25 per page."
version: "v2"
---

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

Path: touchSMS API › Webhook subscriptions

`GET /v2/webhook-subscriptions`

Returns your webhook subscriptions, newest first, 25 per page.

## Authentication

- `basicAuth`, http, header `Authorization`

## Query parameters

- `page` (`listWebhookSubscriptions.query.page`; integer, optional) — Page number. Prefer following `links.next` until it is `null`.
  - min 1; default `1`

## Code samples

### cURL

```bash
curl --request GET \
  --url https://app.touchsms.com.au/api/v2/webhook-subscriptions \
  --header 'Authorization: Basic <credentials>'
```

### TypeScript

```typescript
const url = 'https://app.touchsms.com.au/api/v2/webhook-subscriptions';
const options = {method: 'GET', headers: {Authorization: 'Basic <credentials>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://app.touchsms.com.au/api/v2/webhook-subscriptions"

headers = {"Authorization": "Basic <credentials>"}

response = requests.get(url, headers=headers)

print(response.text)
```

## Responses

### 200

A page of webhook subscriptions.

#### Example

```json
{
  "data": [
    {
      "id": 123,
      "status": "Active",
      "event": "message_received",
      "include_sent_status": false,
      "name": "Inbound to CRM",
      "url": "https://example.com/hooks/inbound",
      "request_method": "POST",
      "request_encoding_type": "json",
      "headers": [
        {
          "key": "X-Api-Key",
          "value": "abc123"
        }
      ],
      "created_at": "2024-02-02T23:51:19Z",
      "updated_at": "2024-03-11T02:14:07Z"
    }
  ],
  "links": {
    "first": "https://app.touchsms.com.au/api/v2/contacts?page=1",
    "last": "https://app.touchsms.com.au/api/v2/contacts?page=8",
    "prev": null,
    "next": "https://app.touchsms.com.au/api/v2/contacts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 8,
    "path": "https://app.touchsms.com.au/api/v2/contacts",
    "per_page": 50,
    "to": 50,
    "total": 400
  }
}
```

- `data` (`listWebhookSubscriptions.response.200.data`; array<object>, optional)
  - `id` (`listWebhookSubscriptions.response.200.data.id`; integer, optional)
  - `status` (`listWebhookSubscriptions.response.200.data.status`; string, optional) — `Disabled Failing` means the subscription was disabled automatically after repeated delivery failures and receives no events until re-enabled.
    - one of `"Active"`, `"Disabled"`, `"Disabled Failing"`
  - `event` (`listWebhookSubscriptions.response.200.data.event`; string, optional) — - `message_received`: an inbound message was received. - `message_dlr`: a delivery receipt was received for an outbound message. - `optout_created`: a number opted out. - `message_received_3cx`: an inbound message, formatted for 3CX.
    - one of `"message_received"`, `"message_dlr"`, `"optout_created"`, `"message_received_3cx"`
  - `include_sent_status` (`listWebhookSubscriptions.response.200.data.include_sent_status`; boolean, optional) — Whether a `message_dlr` subscription also receives `sent` receipts. Always `false` for other events.
  - `name` (`listWebhookSubscriptions.response.200.data.name`; string, optional)
  - `url` (`listWebhookSubscriptions.response.200.data.url`; string, optional)
    - format `uri`
  - `request_method` (`listWebhookSubscriptions.response.200.data.request_method`; string, optional)
    - one of `"POST"`, `"GET"`
  - `request_encoding_type` (`listWebhookSubscriptions.response.200.data.request_encoding_type`; string | null, optional)
    - one of `"json"`, `"form"`, `null`
  - `headers` (`listWebhookSubscriptions.response.200.data.headers`; array<object>, optional)
    - `key` (`listWebhookSubscriptions.response.200.data.headers.key`; string, required) — A valid HTTP header name.
      - minLength 3; maxLength 50
    - `value` (`listWebhookSubscriptions.response.200.data.headers.value`; string, required)
      - minLength 3; maxLength 200
  - `created_at` (`listWebhookSubscriptions.response.200.data.created_at`; string, optional)
    - format `date-time`
  - `updated_at` (`listWebhookSubscriptions.response.200.data.updated_at`; string, optional)
    - format `date-time`
- `links` (`listWebhookSubscriptions.response.200.links`; object, optional) — Links to other pages. `next` is `null` on the last page.
  - example `{"first":"https://app.touchsms.com.au/api/v2/contacts?page=1","last":"https://app.touchsms.com.au/api/v2/contacts?page=8","prev":null,"next":"https://app.touchsms.com.au/api/v2/contacts?page=2"}`
  - `first` (`listWebhookSubscriptions.response.200.links.first`; string | null, optional)
    - format `uri`
  - `last` (`listWebhookSubscriptions.response.200.links.last`; string | null, optional)
    - format `uri`
  - `prev` (`listWebhookSubscriptions.response.200.links.prev`; string | null, optional)
    - format `uri`
  - `next` (`listWebhookSubscriptions.response.200.links.next`; string | null, optional)
    - format `uri`
- `meta` (`listWebhookSubscriptions.response.200.meta`; object, optional) — Position in the result set. Read `per_page` rather than assuming a page size.
  - example `{"current_page":1,"from":1,"last_page":8,"path":"https://app.touchsms.com.au/api/v2/contacts","per_page":50,"to":50,"total":400}`
  - `current_page` (`listWebhookSubscriptions.response.200.meta.current_page`; integer, optional)
  - `from` (`listWebhookSubscriptions.response.200.meta.from`; integer | null, optional)
  - `last_page` (`listWebhookSubscriptions.response.200.meta.last_page`; integer, optional)
  - `path` (`listWebhookSubscriptions.response.200.meta.path`; string, optional)
    - format `uri`
  - `per_page` (`listWebhookSubscriptions.response.200.meta.per_page`; integer, optional)
  - `to` (`listWebhookSubscriptions.response.200.meta.to`; integer | null, optional)
  - `total` (`listWebhookSubscriptions.response.200.meta.total`; integer, optional)
  - `links` (`listWebhookSubscriptions.response.200.meta.links`; array<object>, optional) — Page links for building pagination controls.
    - `url` (`listWebhookSubscriptions.response.200.meta.links.url`; string | null, optional)
    - `label` (`listWebhookSubscriptions.response.200.meta.links.label`; string, optional)
    - `active` (`listWebhookSubscriptions.response.200.meta.links.active`; boolean, optional)

### 401

Missing, malformed or invalid API credentials.

#### Example

```json
{
  "message": "Unauthenticated."
}
```

- `message` (`listWebhookSubscriptions.response.401.message`; string, required)


Source: https://dev.touchsms.com.au/api/webhook-subscriptions/list/index.md