## 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](/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

- `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.

  - `PhoneNumbers param.Field[[]string]`

    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

- `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

  - `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

    - `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

  - `UpdatedAt Time`

    When the subscription was last updated

  - `PhoneNumbers []string`

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

### Example

```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)
}
```

#### 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"
  ]
}
```