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_numbersto only receive events for specific lines - If omitted, events from all phone numbers are delivered (default behavior)
- Use multiple subscriptions with different
phone_numbersto route different lines to different endpoints - Each
target_urlcan 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 Standard Webhooks headers (
webhook-id,webhook-timestamp,webhook-signature) for signature verification - Legacy
X-Webhook-*headers are also sent for backwards compatibility (deprecated) - See Verifying Webhook Signatures for verification details
- Failed deliveries (5xx, 429, network errors) are retried with exponential backoff for up to 30 minutes
- Client errors (4xx except 429) are not retried
Parameters
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.
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"
],
"routing_id_header": "X-Chat-Id",
"routing_key_header": "X-Route-Token"
}{
"error": {
"status": 400,
"code": 1002,
"message": "Phone number must be in E.164 format",
"doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/1xxx/1002/"
},
"success": false
}{
"error": {
"status": 401,
"code": 2004,
"message": "Unauthorized - missing or invalid authentication token",
"doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2004/"
},
"success": false
}{
"error": {
"status": 500,
"code": 3006,
"message": "Internal server error",
"doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/3xxx/3006/"
},
"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"
],
"routing_id_header": "X-Chat-Id",
"routing_key_header": "X-Route-Token"
}{
"error": {
"status": 400,
"code": 1002,
"message": "Phone number must be in E.164 format",
"doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/1xxx/1002/"
},
"success": false
}{
"error": {
"status": 401,
"code": 2004,
"message": "Unauthorized - missing or invalid authentication token",
"doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/2xxx/2004/"
},
"success": false
}{
"error": {
"status": 500,
"code": 3006,
"message": "Internal server error",
"doc_url": "https://docs.linqapp.com/channel/imessage/error/codes/3xxx/3006/"
},
"success": false
}