# 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](/docs/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 ### Parameters - `subscribed_events: List[WebhookEventType]` List of event types to subscribe to - `"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. - `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. ### Returns - `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 - `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 - `"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 - `updated_at: datetime` When the subscription was last updated - `phone_numbers: Optional[List[str]]` Phone numbers this subscription filters for. If null or empty, events from all phone numbers are delivered. ### Example ```python 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) ``` #### Response ```json { "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" ] } ``` ## List all webhook subscriptions `webhook_subscriptions.list() -> WebhookSubscriptionListResponse` **get** `/v3/webhook-subscriptions` Retrieve all webhook subscriptions for the authenticated partner. Returns a list of active and inactive subscriptions with their configuration and status. ### Returns - `class WebhookSubscriptionListResponse: …` - `subscriptions: List[WebhookSubscription]` List of webhook subscriptions - `id: str` Unique identifier for the webhook subscription - `created_at: datetime` When the subscription was created - `is_active: bool` Whether this subscription is currently active - `subscribed_events: List[WebhookEventType]` List of event types this subscription receives - `"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 - `updated_at: datetime` When the subscription was last updated - `phone_numbers: Optional[List[str]]` Phone numbers this subscription filters for. If null or empty, events from all phone numbers are delivered. ### Example ```python 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_subscriptions = client.webhook_subscriptions.list() print(webhook_subscriptions.subscriptions) ``` #### Response ```json { "subscriptions": [ { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "created_at": "2024-01-15T10:30:00Z", "is_active": true, "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" ] } ] } ``` ## Get a webhook subscription by ID `webhook_subscriptions.retrieve(strsubscription_id) -> WebhookSubscription` **get** `/v3/webhook-subscriptions/{subscriptionId}` Retrieve details for a specific webhook subscription including its target URL, subscribed events, and current status. ### Parameters - `subscription_id: str` ### Returns - `class WebhookSubscription: …` - `id: str` Unique identifier for the webhook subscription - `created_at: datetime` When the subscription was created - `is_active: bool` Whether this subscription is currently active - `subscribed_events: List[WebhookEventType]` List of event types this subscription receives - `"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 - `updated_at: datetime` When the subscription was last updated - `phone_numbers: Optional[List[str]]` Phone numbers this subscription filters for. If null or empty, events from all phone numbers are delivered. ### Example ```python 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.retrieve( "b2c3d4e5-f6a7-8901-bcde-f23456789012", ) print(webhook_subscription.id) ``` #### Response ```json { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "created_at": "2024-01-15T10:30:00Z", "is_active": true, "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" ] } ``` ## Update a webhook subscription `webhook_subscriptions.update(strsubscription_id, WebhookSubscriptionUpdateParams**kwargs) -> WebhookSubscription` **put** `/v3/webhook-subscriptions/{subscriptionId}` Update an existing webhook subscription. You can modify the target URL, subscribed events, or activate/deactivate the subscription. **Note:** The signing secret cannot be changed via this endpoint. ### Parameters - `subscription_id: str` - `is_active: Optional[bool]` Activate or deactivate the subscription - `phone_numbers: Optional[Sequence[str]]` Updated list of phone numbers to filter events for. Set to a non-empty array to filter events to specific phone numbers. Set to an empty array or null to remove the filter and receive events from all phone numbers. Phone numbers must be in E.164 format. - `subscribed_events: Optional[List[WebhookEventType]]` Updated list of event types to subscribe to - `"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: Optional[str]` New target URL for webhook events ### Returns - `class WebhookSubscription: …` - `id: str` Unique identifier for the webhook subscription - `created_at: datetime` When the subscription was created - `is_active: bool` Whether this subscription is currently active - `subscribed_events: List[WebhookEventType]` List of event types this subscription receives - `"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 - `updated_at: datetime` When the subscription was last updated - `phone_numbers: Optional[List[str]]` Phone numbers this subscription filters for. If null or empty, events from all phone numbers are delivered. ### Example ```python 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.update( subscription_id="b2c3d4e5-f6a7-8901-bcde-f23456789012", target_url="https://webhooks.example.com/linq/events", ) print(webhook_subscription.id) ``` #### Response ```json { "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012", "created_at": "2024-01-15T10:30:00Z", "is_active": true, "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" ] } ``` ## Delete a webhook subscription `webhook_subscriptions.delete(strsubscription_id)` **delete** `/v3/webhook-subscriptions/{subscriptionId}` Delete a webhook subscription. ### Parameters - `subscription_id: str` ### Example ```python 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 ) client.webhook_subscriptions.delete( "b2c3d4e5-f6a7-8901-bcde-f23456789012", ) ``` #### Response ```json { "error": { "status": 401, "code": 2004, "message": "Unauthorized - missing or invalid authentication token" }, "success": false } ``` ## Domain Types ### Webhook Subscription - `class WebhookSubscription: …` - `id: str` Unique identifier for the webhook subscription - `created_at: datetime` When the subscription was created - `is_active: bool` Whether this subscription is currently active - `subscribed_events: List[WebhookEventType]` List of event types this subscription receives - `"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 - `updated_at: datetime` When the subscription was last updated - `phone_numbers: Optional[List[str]]` Phone numbers this subscription filters for. If null or empty, events from all phone numbers are delivered. ### Webhook Subscription Create Response - `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 - `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 - `"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 - `updated_at: datetime` When the subscription was last updated - `phone_numbers: Optional[List[str]]` Phone numbers this subscription filters for. If null or empty, events from all phone numbers are delivered. ### Webhook Subscription List Response - `class WebhookSubscriptionListResponse: …` - `subscriptions: List[WebhookSubscription]` List of webhook subscriptions - `id: str` Unique identifier for the webhook subscription - `created_at: datetime` When the subscription was created - `is_active: bool` Whether this subscription is currently active - `subscribed_events: List[WebhookEventType]` List of event types this subscription receives - `"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 - `updated_at: datetime` When the subscription was last updated - `phone_numbers: Optional[List[str]]` Phone numbers this subscription filters for. If null or empty, events from all phone numbers are delivered.