---
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.

- [cURL](#tab-panel-143)
- [TypeScript](#tab-panel-144)
- [Python](#tab-panel-145)
- [Go](#tab-panel-146)

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://webhooks.example.com/linq/events?version=2026-02-03",
      "subscribed_events": [
        "message.sent",
        "message.delivered",
        "message.read"
      ]
    }'
```

```
await client.webhookSubscriptions.create({
  target_url: "https://webhooks.example.com/linq/events?version=2026-02-03",
  subscribed_events: ["message.sent", "message.delivered", "message.read"],
});
```

```
client.webhookSubscriptions.create(
    target_url="https://webhooks.example.com/linq/events?version=2026-02-03",
    subscribed_events=["message.sent", "message.delivered", "message.read"],
)
```

```
client.WebhookSubscriptions.Create(context.TODO(), linq.WebhookSubscriptionNewParams{
  TargetUrl: linq.F("https://webhooks.example.com/linq/events?version=2026-02-03"),
  SubscribedEvents: linq.F([]string{"message.sent", "message.delivered", "message.read"}),
})
```

### 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.

- [cURL](#tab-panel-147)
- [TypeScript](#tab-panel-148)
- [Python](#tab-panel-149)
- [Go](#tab-panel-150)

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://webhooks.example.com/linq/line1",
      "subscribed_events": [
        "message.sent",
        "message.received"
      ],
      "phone_numbers": [
        "+12025551234"
      ]
    }'
```

```
await client.webhookSubscriptions.create({
  target_url: "https://webhooks.example.com/linq/line1",
  subscribed_events: ["message.sent", "message.received"],
  phone_numbers: ["+12025551234"],
});
```

```
client.webhookSubscriptions.create(
    target_url="https://webhooks.example.com/linq/line1",
    subscribed_events=["message.sent", "message.received"],
    phone_numbers=["+12025551234"],
)
```

```
client.WebhookSubscriptions.Create(context.TODO(), linq.WebhookSubscriptionNewParams{
  TargetUrl: linq.F("https://webhooks.example.com/linq/line1"),
  SubscribedEvents: linq.F([]string{"message.sent", "message.received"}),
  PhoneNumbers: linq.F([]string{"+12025551234"}),
})
```

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)