Skip to main content

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.

HeaderValue
X-Hub-Signature-256sha256=<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.

HeaderValue
X-Line-SignatureBase64-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.

warning

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.