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.

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 for the full endpoint specification.

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.

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.

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.

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.

Related

• Webhooks — versioning, headers, signature verification, delivery guarantees, event types
• Error 2010 — webhook subscription not found
• Error 4003 — webhook delivery failed
• API Reference: Webhook Subscriptions