Webhook Security

Every webhook payload received by Convotic is verified for authenticity before processing. Each platform uses a different signature mechanism. This page documents how verification works for each platform and best practices for securing your webhook pipeline.

Signature verification by platform

Instagram / Messenger (Meta)

Meta signs webhook payloads using HMAC-SHA256 with your App Secret.

Header	Value
X-Hub-Signature-256	sha256=<hex_digest>

Verification logic:

import crypto from "crypto";

function verifyMetaSignature(
  payload: string,
  signature: string,
  appSecret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", appSecret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature.replace("sha256=", "")),
    Buffer.from(expected)
  );
}

LINE

LINE signs webhook payloads using HMAC-SHA256 with your Channel Secret, encoded as Base64.

Header	Value
X-Line-Signature	Base64-encoded HMAC-SHA256 digest

Verification logic:

import crypto from "crypto";

function verifyLineSignature(
  payload: string,
  signature: string,
  channelSecret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", channelSecret)
    .update(payload)
    .digest("base64");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

WhatsApp (Meta)

WhatsApp uses the same verification mechanism as Instagram/Messenger (HMAC-SHA256 with X-Hub-Signature-256). See the Meta section above.

Telegram

Telegram does not sign individual webhook payloads. Instead, security is achieved through:

1. Secret webhook URL -- the webhook URL includes a secret token path segment that only Telegram knows.
2. IP allowlisting -- Telegram sends webhooks from a known set of IP ranges (149.154.160.0/20 and 91.108.4.0/22).
3. X-Telegram-Bot-Api-Secret-Token -- an optional secret token header set when registering the webhook.

function verifyTelegramSecret(
  headerToken: string,
  expectedToken: string
): boolean {
  return crypto.timingSafeEqual(
    Buffer.from(headerToken),
    Buffer.from(expectedToken)
  );
}

Best practices

Always verify signatures

Never skip signature verification, even in development. Convotic verifies all signatures before publishing events to the message broker.

Use timing-safe comparison

Always use crypto.timingSafeEqual() (or equivalent) for signature comparison to prevent timing attacks. Never use === for signature comparison.

Respond quickly

Platforms expect a 200 OK response within a few seconds. Convotic acknowledges the webhook immediately and processes it asynchronously via Pub/Sub.

警告

If your webhook endpoint does not respond within the platform's timeout (typically 5--20 seconds), the platform may retry or eventually disable the webhook.

Monitor for failures

Review webhook delivery status in Settings > Webhooks > Event Log. Investigate any events with failed status, as they may indicate signature verification failures, malformed payloads, or infrastructure issues.

Keep secrets secure

• Store platform secrets (App Secret, Channel Secret) in a secrets manager.
• Rotate secrets periodically.
• If a secret is compromised, rotate it immediately and update the corresponding Block configuration in Convotic.

IP allowlisting

For additional security, you can restrict inbound traffic to your webhook endpoints to the IP ranges used by each platform. Consult each platform's documentation for their current IP ranges.