Skip to content
Linq

Webhook Events

Webhook Subscriptions allow you to receive real-time notifications when events occur on your account.

Configure webhook endpoints to receive call_voice.* events as calls progress.

Failed deliveries (5xx, 429, network errors) are retried with exponential backoff for up to 30 minutes. Each event includes a unique ID for deduplication.

Webhook Headers

All webhook requests include two sets of headers. If you have an existing integration using the X-Webhook-* headers, nothing changes — those headers are still sent on every delivery and work exactly as before. The new webhook-* headers follow the Standard Webhooks specification. You can safely ignore them if your current verification code works and you don’t want to use this convention.

Used by our SDK and any Standard Webhooks library.

HeaderDescription
webhook-idUnique event identifier (use as idempotency key)
webhook-timestampUnix timestamp (seconds) when the webhook was sent
webhook-signatureStandard Webhooks signature (v1,{base64} format)

Legacy Headers (Deprecated)

Still sent on every delivery for backwards compatibility. Existing verification code using these headers continues to work — no changes required.

HeaderDescription
X-Webhook-Event(deprecated) Event type (e.g., call_voice.ringing)
X-Webhook-Subscription-ID(deprecated) Webhook subscription ID
X-Webhook-Timestamp(deprecated) Unix timestamp (seconds)
X-Webhook-Signature(deprecated) HMAC-SHA256 signature (hex-encoded)

Signing Secrets

Signing secrets use the Standard Webhooks format: a whsec_ prefix followed by base64-encoded random bytes (e.g., whsec_bGlucS1leGFtcGxlLXNlY3JldC1kby1ub3QtdXNlLTMyYg==).

Strip the whsec_ prefix and base64-decode the remainder to get the raw key bytes.

Verifying Webhook Signatures

Webhooks are signed following the Standard Webhooks specification. You can use any Standard Webhooks library to verify signatures, or implement verification manually:

Signed content: {webhook-id}.{webhook-timestamp}.{body}

Verification Steps:

  1. Extract the webhook-id, webhook-timestamp, and webhook-signature headers
  2. Reject if the timestamp is more than 5 minutes from the current time, in either direction (replay protection)
  3. Get the raw request body bytes (do not parse and re-serialize)
  4. Construct signed content: "{webhook-id}.{webhook-timestamp}.{body}"
  5. Strip the whsec_ prefix from your secret and base64-decode to get key bytes
  6. Compute HMAC-SHA256 using the key bytes over the signed content
  7. Base64-encode the result and compare with the value after v1, in webhook-signature
  8. Use constant-time comparison to prevent timing attacks

Example (Python):

import base64, hashlib, hmac, time

TOLERANCE_SECONDS = 5 * 60

def verify_webhook(secret: str, body: bytes, headers) -> bool:
    # body: the raw request body bytes, before any JSON parsing (Flask: request.get_data())
    msg_id = headers.get('webhook-id')
    timestamp = headers.get('webhook-timestamp')
    signature = headers.get('webhook-signature')
    if not (msg_id and timestamp and signature):
        return False

    try:
        sent_at = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() - sent_at) > TOLERANCE_SECONDS:
        return False  # stale or from the future: possible replay

    key = base64.b64decode(secret.removeprefix('whsec_'))
    signed_content = f'{msg_id}.{timestamp}.'.encode() + body
    expected = base64.b64encode(
        hmac.new(key, signed_content, hashlib.sha256).digest()
    )

    for sig in signature.split(' '):
        version, _, value = sig.partition(',')
        if version == 'v1' and hmac.compare_digest(expected, value.encode()):
            return True
    return False

Example (Node.js):

const crypto = require('crypto');

const TOLERANCE_SECONDS = 5 * 60;

// rawBody: the request body exactly as received, as a Buffer or string
// (Express: express.raw({ type: 'application/json' })), not parsed JSON.
function verifyWebhook(secret, rawBody, headers) {
  const msgId = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signature = headers['webhook-signature'];
  if (!msgId || !timestamp || !signature) return false;

  if (!/^\d+$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) {
    return false; // stale or from the future: possible replay
  }

  const secretStr = secret.startsWith('whsec_') ? secret.slice(6) : secret;
  const key = Buffer.from(secretStr, 'base64');
  const expected = crypto
    .createHmac('sha256', key)
    .update(`${msgId}.${timestamp}.`)
    .update(rawBody)
    .digest();

  return signature.split(' ').some((sig) => {
    if (!sig.startsWith('v1,')) return false;
    const received = Buffer.from(sig.slice(3), 'base64');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

Security Best Practices:

  • Reject webhooks whose timestamp is more than 5 minutes from the current time, to prevent replay attacks
  • Always use constant-time comparison for signature verification
  • Store your signing secret securely (e.g., environment variable, secrets manager)
  • Return a 2xx status code quickly, then process the webhook asynchronously
ModelsExpand Collapse
WebhookEventType = "call_voice.initiated" or "call_voice.ringing" or "call_voice.answered" or 73 more

Valid webhook event types that can be subscribed to.

Note: message.edited is only delivered to subscriptions using webhook_version: "2026-02-03". Subscribing to this event on a v2025 subscription will not produce any deliveries.

One of the following:
"call_voice.initiated"
"call_voice.ringing"
"call_voice.answered"
"call_voice.ended"
"call_voice.failed"
"call_voice.declined"
"call_voice.no_answer"
"message.sent"
"message.received"
"message.read"
"message.delivered"
"message.failed"
"message.edited"
"reaction.added"
"reaction.removed"
"poll.received"
"poll.failed"
"poll.sent"
"poll.delivered"
"poll.read"
"poll.updated"
"poll.vote.added"
"poll.vote.removed"
"poll.reaction.added"
"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.background_updated"
"chat.background_update_failed"
"chat.typing_indicator.started"
"chat.typing_indicator.stopped"
"phone_number.status_updated"
"phone_number.assigned"
"phone_number.released"
"phone_number.line_type_updated"
"contact_card.received"
"location.sharing.started"
"location.sharing.stopped"
"payment.succeeded"
"payment.canceled"
"payment.expired"
"payment.declined"
"payment.authorized"
"connection.created"
"connection.revoked"
"zero_day_retention.updated"
"phone_number.forwarding_updated"
"environment.line_moved"
"contact_card.created"
"contact_card.updated"
"contact_card.deleted"
"api_token.created"
"api_token.renamed"
"api_token.expiry_scheduled"
"api_token.expired"
"api_token.activated"
"api_token.deleted"
"environment.created"
"environment.renamed"
"environment.deleted"
"webhook_subscription.created"
"webhook_subscription.deleted"
"webhook_subscription.target_url_changed"
"webhook_subscription.enabled"
"webhook_subscription.disabled"
"webhook_subscription.events.updated"
"webhook_subscription.phone_numbers.updated"
"webhook_subscription.routing_headers_set"
"webhook_subscription.routing_headers_cleared"
"team_member.added"
"team_member.signed_in"
"team_member.signed_out"
WebhookEventListResponse object { doc_url, events }
doc_url: "https://docs.linqapp.com/channel/imessage/guides/webhooks/events"

URL to the webhook events documentation

formaturi
events: array of WebhookEventType

List of all available webhook event types

One of the following:
"call_voice.initiated"
"call_voice.ringing"
"call_voice.answered"
"call_voice.ended"
"call_voice.failed"
"call_voice.declined"
"call_voice.no_answer"
"message.sent"
"message.received"
"message.read"
"message.delivered"
"message.failed"
"message.edited"
"reaction.added"
"reaction.removed"
"poll.received"
"poll.failed"
"poll.sent"
"poll.delivered"
"poll.read"
"poll.updated"
"poll.vote.added"
"poll.vote.removed"
"poll.reaction.added"
"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.background_updated"
"chat.background_update_failed"
"chat.typing_indicator.started"
"chat.typing_indicator.stopped"
"phone_number.status_updated"
"phone_number.assigned"
"phone_number.released"
"phone_number.line_type_updated"
"contact_card.received"
"location.sharing.started"
"location.sharing.stopped"
"payment.succeeded"
"payment.canceled"
"payment.expired"
"payment.declined"
"payment.authorized"
"connection.created"
"connection.revoked"
"zero_day_retention.updated"
"phone_number.forwarding_updated"
"environment.line_moved"
"contact_card.created"
"contact_card.updated"
"contact_card.deleted"
"api_token.created"
"api_token.renamed"
"api_token.expiry_scheduled"
"api_token.expired"
"api_token.activated"
"api_token.deleted"
"environment.created"
"environment.renamed"
"environment.deleted"
"webhook_subscription.created"
"webhook_subscription.deleted"
"webhook_subscription.target_url_changed"
"webhook_subscription.enabled"
"webhook_subscription.disabled"
"webhook_subscription.events.updated"
"webhook_subscription.phone_numbers.updated"
"webhook_subscription.routing_headers_set"
"webhook_subscription.routing_headers_cleared"
"team_member.added"
"team_member.signed_in"
"team_member.signed_out"