twitter-webhooks

Twitter / X Webhooks

Twitter/X delivers account activity through the Account Activity API. Your public HTTPS endpoint must do two things:

1. Answer the CRC (Challenge-Response Check) — X sends a GET request with a crc_token query parameter at registration, roughly hourly, and on demand. You must reply within the timeout with a response_token, or the webhook is marked invalid and delivery stops.
2. Verify POST deliveries — every event POST carries an x-twitter-webhooks-signature header you validate before processing.

Both use the same primitive: HMAC-SHA256 keyed with your app's consumer secret (API secret key), base64-encoded, prefixed with sha256=. Use the consumer secret — not the bearer token or user access token.

When to Use This Skill

• How do I receive Twitter/X (Account Activity API) webhooks?
• How do I verify the x-twitter-webhooks-signature header?
• How do I respond to the X CRC / crc_token challenge?
• How do I handle tweet_create_events, follow_events, or direct_message_events?
• Why is my X webhook being marked invalid / why did delivery stop?

Verification (core)

X signs the raw request body (for POST events) or the crc_token value (for the CRC GET) with HMAC-SHA256 using the consumer secret, base64-encodes it, and prepends sha256=. The exact same helper produces both values:

const crypto = require('crypto');

// sha256= + base64(HMAC-SHA256(consumerSecret, message))
function buildSignature(message, consumerSecret) {
  return 'sha256=' + crypto
    .createHmac('sha256', consumerSecret)
    .update(message)
    .digest('base64');
}

// CRC GET: reply { response_token: buildSignature(crc_token, secret) }
// POST:    compare buildSignature(rawBody, secret) to the header, timing-safe
function verifyTwitterSignature(rawBody, signatureHeader, consumerSecret) {
  if (!signatureHeader || !consumerSecret) return false;
  const expected = buildSignature(rawBody, consumerSecret);
  try {
    return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected));
  } catch {
    return false; // length mismatch = invalid
  }
}