---
title: Webhook Subscriptions | API Docs
description: Create, list, retrieve, update, and delete webhook subscriptions.
---

A **webhook subscription** tells Linq to POST events to a URL you own. Each subscription has a target URL, a list of subscribed events, an optional phone-number filter, and a signing secret used to verify incoming requests. For handling events on your server (signature verification, envelope shape, event types), see [Webhooks](/guides/webhooks/index.md).

## Create a subscription

Creating a subscription returns a `signing_secret` in the response — **store it securely, it cannot be retrieved later**. You use it to verify the HMAC signature on every inbound webhook. See the [Create Subscription API reference](/api/resources/webhook_subscriptions/methods/create/index.md) for the full endpoint specification.

Terminal window

```
curl -X POST https://api.linqapp.com/api/partner/v3/webhook-subscriptions \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://your-server.com/webhook?version=2026-02-03",
    "subscribed_events": [
      "message.sent",
      "message.received",
      "message.delivered",
      "message.read",
      "message.failed"
    ]
  }'
```

```
const subscription = await client.webhookSubscriptions.create({
  target_url: 'https://your-server.com/webhook?version=2026-02-03',
  subscribed_events: [
    'message.sent',
    'message.received',
    'message.delivered',
    'message.read',
    'message.failed',
  ],
});
```

```
subscription = client.webhook_subscriptions.create(
    target_url="https://your-server.com/webhook?version=2026-02-03",
    subscribed_events=[
        "message.sent",
        "message.received",
        "message.delivered",
        "message.read",
        "message.failed",
    ],
)
```

### Filtering by phone number

Pass a `phone_numbers` array to route only events from specific lines to this subscription. Omit it to receive events from every line on your account.

```
{
  "target_url": "https://your-server.com/support-webhook",
  "subscribed_events": ["message.received"],
  "phone_numbers": ["+12223334444", "+15556667777"]
}
```

Each `target_url` can only be used **once per account**. To route different lines to different endpoints, give each subscription a unique URL — for example by appending a query parameter (`?line=support`).

## List subscriptions

Return every webhook subscription on the authenticated partner account — active and inactive. See the [List Subscriptions API reference](/api/resources/webhook_subscriptions/methods/list/index.md).

## Retrieve a subscription

Fetch a single subscription by ID, including its target URL, subscribed events, phone-number filter, and active status. See the [Retrieve Subscription API reference](/api/resources/webhook_subscriptions/methods/retrieve/index.md).

## Update a subscription

Change the target URL, subscribed events, phone-number filter, or active flag. Fields you omit keep their existing values. The **signing secret cannot be changed** via this endpoint — to rotate it, delete and recreate the subscription. See the [Update Subscription API reference](/api/resources/webhook_subscriptions/methods/update/index.md).

Common update patterns:

- **Pause a subscription** — `is_active: false`. Events stop flowing until you flip it back.
- **Add or remove events** — replace `subscribed_events` with the full desired list.
- **Change filter** — set `phone_numbers` to a new array, or pass an empty array / `null` to remove the filter.

## Delete a subscription

Permanently remove a subscription. Events stop flowing immediately and the signing secret is discarded. See the [Delete Subscription API reference](/api/resources/webhook_subscriptions/methods/delete/index.md).

## Related

- [Webhooks](/guides/webhooks/index.md) — versioning, headers, signature verification, delivery guarantees, event types
- [Error 2010 — webhook subscription not found](/error/codes/2xxx/2010/index.md)
- [Error 4003 — webhook delivery failed](/error/codes/4xxx/4003/index.md)
- [API Reference: Webhook Subscriptions](/api/resources/webhook_subscriptions/index.md)