Webhooks

Create a new webhook subscription

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 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
post/v3/webhook-subscriptions

Request

  • Base URL: https://api.linqapp.com/api/partner
  • URL: https://api.linqapp.com/api/partner/v3/webhook-subscriptions
  • Auth: HTTP bearer

Request body

target_urlstring uri required

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

subscribed_eventsWebhookEventType[] required

List of event types to subscribe to

phone_numbersstring[]

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.

routing_key_headerstring

Enables delivery affinity. Name of the header carrying an opaque routing token: we send it on each webhook for a chat and read it back from your 2xx response, so your edge can route to the cluster holding that chat. Omit to disable.

routing_id_headerstring

Name of the header carrying the chat id, used to hash-route before a token is learned. Defaults to Linq-Chat-Id. Ignored without routing_key_header.

Example request

{
  "target_url": "https://webhooks.example.com/linq/events",
  "subscribed_events": [
    "message.sent",
    "message.delivered"
  ],
  "phone_numbers": [
    "+12025551234",
    "+12025559876"
  ],
  "routing_key_header": "X-Route-Token",
  "routing_id_header": "X-Chat-Id"
}

Response

Webhook subscription created successfully. The signing_secret is only returned in this response - store it securely.

idstring required

Unique identifier for the webhook subscription

target_urlstring uri required

URL where webhook events will be sent

signing_secretstring required

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

subscribed_eventsWebhookEventType[] required

List of event types this subscription receives

phone_numbersstring[] nullable

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

routing_key_headerstring nullable

Header carrying the routing token. Null disables delivery affinity.

routing_id_headerstring nullable

Header carrying the chat id. Defaults to Linq-Chat-Id when affinity is on.

is_activeboolean required

Whether this subscription is currently active

created_atstring date-time required

When the subscription was created

updated_atstring date-time required

When the subscription was last updated

Example response

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "target_url": "https://webhooks.example.com/linq/events",
  "signing_secret": "whsec_abc123def456",
  "subscribed_events": [
    "message.sent",
    "message.delivered",
    "message.read"
  ],
  "routing_key_header": "X-Route-Token",
  "routing_id_header": "X-Chat-Id",
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.