Skip to main content
Webhooks deliver events from monitored X accounts to your server in real time. Every delivery is signed with HMAC-SHA256 so you can verify authenticity.

​
How It Works

X Account Activity → Xquik Stream → Your Webhook Endpoint
1

Create a monitor

Monitor an X account for specific event types (tweets, replies, quotes, retweets).
2

Register a webhook

Provide an HTTPS URL and select which event types to receive. Xquik generates a signing secret.
3

Receive events

When a monitored account triggers an event, Xquik sends an HTTPS POST to your endpoint with the event payload and an HMAC signature header.
4

Verify & process

Verify the X-Xquik-Signature header using your webhook secret, then process the event.

​
Delivery Format

Webhook events are delivered as HTTPS POST requests.

​
Headers

HeaderValueDescription
Content-Typeapplication/jsonPayload is always JSON
X-Xquik-Signaturesha256=HMAC_HEX_DIGESTHMAC-SHA256 signature for verification

​
Payload Body

{
  "eventType": "tweet.new",
  "username": "elonmusk",
  "data": {
    "tweetId": "1893456789012345678",
    "text": "The future is now.",
    "metrics": {
      "likes": 42000,
      "retweets": 8500,
      "replies": 3200
    }
  }
}
FieldTypeDescription
eventTypestringEvent type (see below)
usernamestringX username of the monitored account
dataobjectEvent-specific payload (varies by type)

​
Event Data Shapes

Each event type includes a data object with type-specific fields.

​
tweet.new

A new original tweet posted by the monitored account. 
{
  "eventType": "tweet.new",
  "username": "elonmusk",
  "data": {
    "tweetId": "1893456789012345678",
    "text": "The future is now.",
    "metrics": {
      "likes": 42000,
      "retweets": 8500,
      "replies": 3200
    }
  }
}

​
tweet.quote

A quote tweet posted by the monitored account. Includes quotedTweetId and quotedUsername referencing the original tweet. 
{
  "eventType": "tweet.quote",
  "username": "elonmusk",
  "data": {
    "tweetId": "1893456789012345679",
    "text": "Interesting take on this.",
    "quotedTweetId": "1893400000000000000",
    "quotedUsername": "SpaceX",
    "metrics": {
      "likes": 18000,
      "retweets": 3200,
      "replies": 1100
    }
  }
}

​
tweet.reply

A reply posted by the monitored account. Includes inReplyToTweetId and inReplyToUsername referencing the parent tweet. 
{
  "eventType": "tweet.reply",
  "username": "elonmusk",
  "data": {
    "tweetId": "1893456789012345680",
    "text": "Great question. Working on it.",
    "inReplyToTweetId": "1893411111111111111",
    "inReplyToUsername": "Tesla",
    "metrics": {
      "likes": 9500,
      "retweets": 1200,
      "replies": 800
    }
  }
}

​
tweet.retweet

A retweet posted by the monitored account. Includes retweetedTweetId and retweetedUsername referencing the original tweet. 
{
  "eventType": "tweet.retweet",
  "username": "elonmusk",
  "data": {
    "tweetId": "1893456789012345681",
    "retweetedTweetId": "1893422222222222222",
    "retweetedUsername": "xai",
    "metrics": {
      "likes": 0,
      "retweets": 0,
      "replies": 0
    }
  }
}

​
Retry Policy

Failed deliveries are retried with exponential backoff (base 1s, multiplier 2x):
AttemptDelay
11 second
22 seconds
34 seconds
48 seconds
516 seconds
After 5 failed attempts, the delivery is marked as exhausted. Check delivery status via the deliveries endpoint.

​
Requirements

  • Endpoint must use HTTPS
  • Endpoint must respond with 2xx within 10 seconds
  • Non-2xx responses or timeouts count as failures

​
Next Steps

Signature Verification

Verify HMAC-SHA256 signatures and implement idempotency.

Testing Webhooks

Test webhook delivery locally with tunnels and mock payloads.