Skip to content
API Docs
V2 (Legacy) API ReferenceGet started
API Reference
Webhook Subscriptions

Create a new webhook subscription

webhook_subscriptions.create(WebhookSubscriptionCreateParams**kwargs) -> WebhookSubscriptionCreateResponse
POST/v3/webhook-subscriptions

Create a new webhook subscription to receive events at a target URL. Upon creation, a signing secret is generated for verifying webhook authenticity. Store this secret securely — it cannot be retrieved later.

Phone Number Filtering:

  • Optionally specify phone_numbers to only receive events for specific lines
  • If omitted, events from all phone numbers are delivered (default behavior)
  • Use multiple subscriptions with different phone_numbers to route different lines to different endpoints
  • Each target_url can only be used once per account. To route different lines to different destinations, use a unique URL per subscription (e.g., append a query parameter: https://example.com/webhook?line=1)

Webhook Delivery:

  • Events are sent via HTTP POST to the target URL
  • Each request includes X-Webhook-Signature and X-Webhook-Timestamp headers
  • Signature is HMAC-SHA256 over {timestamp}.{payload} — see Webhook Events for verification details
  • Failed deliveries (5xx, 429, network errors) are retried up to 10 times over ~25 minutes with exponential backoff
  • Client errors (4xx except 429) are not retried
ParametersExpand Collapse
subscribed_events: List[WebhookEventType]

List of event types to subscribe to

One of the following:
"message.sent"
"message.received"
"message.read"
"message.delivered"
"message.failed"
"message.edited"
"reaction.added"
"reaction.removed"
"participant.added"
"participant.removed"
"chat.created"
"chat.group_name_updated"
"chat.group_icon_updated"
"chat.group_name_update_failed"
"chat.group_icon_update_failed"
"chat.typing_indicator.started"
"chat.typing_indicator.stopped"
"phone_number.status_updated"
"call.initiated"
"call.ringing"
"call.answered"
"call.ended"
"call.failed"
"call.declined"
"call.no_answer"
target_url: str

URL where webhook events will be sent. Must be HTTPS.

formaturi
phone_numbers: Optional[Sequence[str]]

Optional list of phone numbers to filter events for. Only events originating from these phone numbers will be delivered to this subscription. If omitted or empty, events from all phone numbers are delivered. Phone numbers must be in E.164 format.

ReturnsExpand Collapse
class WebhookSubscriptionCreateResponse: …

Response returned when creating a webhook subscription. Includes the signing secret which is only shown once.

id: str

Unique identifier for the webhook subscription

created_at: datetime

When the subscription was created

formatdate-time
is_active: bool

Whether this subscription is currently active

signing_secret: str

Secret for verifying webhook signatures. Store this securely - it cannot be retrieved again.

subscribed_events: List[WebhookEventType]

List of event types this subscription receives

One of the following:
"message.sent"
"message.received"
"message.read"
"message.delivered"
"message.failed"
"message.edited"
"reaction.added"
"reaction.removed"
"participant.added"
"participant.removed"
"chat.created"
"chat.group_name_updated"
"chat.group_icon_updated"
"chat.group_name_update_failed"
"chat.group_icon_update_failed"
"chat.typing_indicator.started"
"chat.typing_indicator.stopped"
"phone_number.status_updated"
"call.initiated"
"call.ringing"
"call.answered"
"call.ended"
"call.failed"
"call.declined"
"call.no_answer"
target_url: str

URL where webhook events will be sent

formaturi
updated_at: datetime

When the subscription was last updated

formatdate-time
phone_numbers: Optional[List[str]]

Phone numbers this subscription filters for. If null or empty, events from all phone numbers are delivered.

Create a new webhook subscription

import os
from linq import LinqAPIV3

client = LinqAPIV3(
    api_key=os.environ.get("LINQ_API_V3_API_KEY"),  # This is the default and can be omitted
)
webhook_subscription = client.webhook_subscriptions.create(
    subscribed_events=["message.sent", "message.delivered", "message.read"],
    target_url="https://webhooks.example.com/linq/events",
)
print(webhook_subscription.id)
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "created_at": "2024-01-15T10:30:00Z",
  "is_active": true,
  "signing_secret": "whsec_abc123def456",
  "subscribed_events": [
    "message.sent",
    "message.delivered",
    "message.read"
  ],
  "target_url": "https://webhooks.example.com/linq/events",
  "updated_at": "2024-01-15T10:30:00Z",
  "phone_numbers": [
    "string"
  ]
}
{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format"
  },
  "success": false
}
{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token"
  },
  "success": false
}
{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error"
  },
  "success": false
}
Returns Examples
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "created_at": "2024-01-15T10:30:00Z",
  "is_active": true,
  "signing_secret": "whsec_abc123def456",
  "subscribed_events": [
    "message.sent",
    "message.delivered",
    "message.read"
  ],
  "target_url": "https://webhooks.example.com/linq/events",
  "updated_at": "2024-01-15T10:30:00Z",
  "phone_numbers": [
    "string"
  ]
}
{
  "error": {
    "status": 400,
    "code": 1002,
    "message": "Phone number must be in E.164 format"
  },
  "success": false
}
{
  "error": {
    "status": 401,
    "code": 2004,
    "message": "Unauthorized - missing or invalid authentication token"
  },
  "success": false
}
{
  "error": {
    "status": 500,
    "code": 3006,
    "message": "Internal server error"
  },
  "success": false
}
© 2026 Linq, Inc. · linqapp.com