API Reference

Webhook Subscriptions

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create a new webhook subscription

client.WebhookSubscriptions.New(ctx, body) (*WebhookSubscriptionNewResponse, error)

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

body WebhookSubscriptionNewParams

SubscribedEvents param.Field[[]WebhookEventType]

List of event types to subscribe to

const WebhookEventTypeMessageSent WebhookEventType = "message.sent"

const WebhookEventTypeMessageReceived WebhookEventType = "message.received"

const WebhookEventTypeMessageRead WebhookEventType = "message.read"

const WebhookEventTypeMessageDelivered WebhookEventType = "message.delivered"

const WebhookEventTypeMessageFailed WebhookEventType = "message.failed"

const WebhookEventTypeMessageEdited WebhookEventType = "message.edited"

const WebhookEventTypeReactionAdded WebhookEventType = "reaction.added"

const WebhookEventTypeReactionRemoved WebhookEventType = "reaction.removed"

const WebhookEventTypeParticipantAdded WebhookEventType = "participant.added"

const WebhookEventTypeParticipantRemoved WebhookEventType = "participant.removed"

const WebhookEventTypeChatCreated WebhookEventType = "chat.created"

const WebhookEventTypeChatGroupNameUpdated WebhookEventType = "chat.group_name_updated"

const WebhookEventTypeChatGroupIconUpdated WebhookEventType = "chat.group_icon_updated"

const WebhookEventTypeChatGroupNameUpdateFailed WebhookEventType = "chat.group_name_update_failed"

const WebhookEventTypeChatGroupIconUpdateFailed WebhookEventType = "chat.group_icon_update_failed"

const WebhookEventTypeChatTypingIndicatorStarted WebhookEventType = "chat.typing_indicator.started"

const WebhookEventTypeChatTypingIndicatorStopped WebhookEventType = "chat.typing_indicator.stopped"

const WebhookEventTypePhoneNumberStatusUpdated WebhookEventType = "phone_number.status_updated"

const WebhookEventTypeCallInitiated WebhookEventType = "call.initiated"

const WebhookEventTypeCallRinging WebhookEventType = "call.ringing"

const WebhookEventTypeCallAnswered WebhookEventType = "call.answered"

const WebhookEventTypeCallEnded WebhookEventType = "call.ended"

const WebhookEventTypeCallFailed WebhookEventType = "call.failed"

const WebhookEventTypeCallDeclined WebhookEventType = "call.declined"

const WebhookEventTypeCallNoAnswer WebhookEventType = "call.no_answer"

TargetURL param.Field[string]

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

formaturi

PhoneNumbers param.Field[[]string]Optional

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

type WebhookSubscriptionNewResponse struct{…}

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

ID string

Unique identifier for the webhook subscription

CreatedAt Time

When the subscription was created

formatdate-time

IsActive bool

Whether this subscription is currently active

SigningSecret string

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

SubscribedEvents []WebhookEventType

List of event types this subscription receives

One of the following:

const WebhookEventTypeMessageSent WebhookEventType = "message.sent"

const WebhookEventTypeMessageReceived WebhookEventType = "message.received"

const WebhookEventTypeMessageRead WebhookEventType = "message.read"

const WebhookEventTypeMessageDelivered WebhookEventType = "message.delivered"

const WebhookEventTypeMessageFailed WebhookEventType = "message.failed"

const WebhookEventTypeMessageEdited WebhookEventType = "message.edited"

const WebhookEventTypeReactionAdded WebhookEventType = "reaction.added"

const WebhookEventTypeReactionRemoved WebhookEventType = "reaction.removed"

const WebhookEventTypeParticipantAdded WebhookEventType = "participant.added"

const WebhookEventTypeParticipantRemoved WebhookEventType = "participant.removed"

const WebhookEventTypeChatCreated WebhookEventType = "chat.created"

const WebhookEventTypeChatGroupNameUpdated WebhookEventType = "chat.group_name_updated"

const WebhookEventTypeChatGroupIconUpdated WebhookEventType = "chat.group_icon_updated"

const WebhookEventTypeChatGroupNameUpdateFailed WebhookEventType = "chat.group_name_update_failed"

const WebhookEventTypeChatGroupIconUpdateFailed WebhookEventType = "chat.group_icon_update_failed"

const WebhookEventTypeChatTypingIndicatorStarted WebhookEventType = "chat.typing_indicator.started"

const WebhookEventTypeChatTypingIndicatorStopped WebhookEventType = "chat.typing_indicator.stopped"

const WebhookEventTypePhoneNumberStatusUpdated WebhookEventType = "phone_number.status_updated"

const WebhookEventTypeCallInitiated WebhookEventType = "call.initiated"

const WebhookEventTypeCallRinging WebhookEventType = "call.ringing"

const WebhookEventTypeCallAnswered WebhookEventType = "call.answered"

const WebhookEventTypeCallEnded WebhookEventType = "call.ended"

const WebhookEventTypeCallFailed WebhookEventType = "call.failed"

const WebhookEventTypeCallDeclined WebhookEventType = "call.declined"

const WebhookEventTypeCallNoAnswer WebhookEventType = "call.no_answer"

TargetURL string

URL where webhook events will be sent

formaturi

UpdatedAt Time

When the subscription was last updated

formatdate-time

PhoneNumbers []stringOptional

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

Create a new webhook subscription

Go

HTTP

TypeScript

Python

Go

package main

import (
  "context"
  "fmt"

  "github.com/linq-team/linq-go"
  "github.com/linq-team/linq-go/option"
)

func main() {
  client := linqgo.NewClient(
    option.WithAPIKey("My API Key"),
  )
  webhookSubscription, err := client.WebhookSubscriptions.New(context.TODO(), linqgo.WebhookSubscriptionNewParams{
    SubscribedEvents: []linqgo.WebhookEventType{linqgo.WebhookEventTypeMessageSent, linqgo.WebhookEventTypeMessageDelivered, linqgo.WebhookEventTypeMessageRead},
    TargetURL: "https://webhooks.example.com/linq/events",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", webhookSubscription.ID)
}

200 example

400 example

401 example

500 example

{
  "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

200 example

400 example

401 example

500 example

{
  "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
}