Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.xquik.com/llms.txt

Use this file to discover all available pages before exploring further.

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. Use webhooks when tweet.new, tweet.reply, tweet.quote, or tweet.retweet events must reach your app without polling. The setup returns a monitor ID, webhook ID, one-time signing secret, and signed JSON deliveries. Webhook operations are free. Active monitors cost 21 credits/hour and include stored events plus webhook delivery.

Account or keyword monitor

Output: monitor ID, username or keyword, and selected event types. Cost: 21 credits/hour while active.

Webhook endpoint

Output: webhook ID, URL, event types, and one-time secret. Cost: free.

Signed delivery

Output: HTTPS POST with JSON body and HMAC headers. Cost: included with the active monitor.

​
Quick setup

Get webhooks working in 3 steps:
1

Create a monitor

Start monitoring an X account for specific event types.
curl -X POST https://xquik.com/api/v1/monitors \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "elonmusk",
    "eventTypes": ["tweet.new", "tweet.reply"]
  }' | jq
2

Register a webhook

Provide an HTTPS URL and select which event types to receive. Xquik generates a signing secret. Store it securely, it is only returned once.
curl -X POST https://xquik.com/api/v1/webhooks \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "eventTypes": ["tweet.new", "tweet.reply"]
  }' | jq
Response:
{
  "id": "15",
  "url": "https://your-server.com/webhook",
  "eventTypes": ["tweet.new", "tweet.reply"],
  "secret": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "createdAt": "2026-02-24T10:30:00.000Z"
}
3

Verify signatures

When events arrive, verify the X-Xquik-Signature header using your webhook secret to confirm authenticity. See Signature Verification for implementation details.Send a test payload before connecting production logic:
curl -X POST https://xquik.com/api/v1/webhooks/15/test \
  -H "x-api-key: xq_YOUR_KEY_HERE" | jq

​
How it works

Monitor event -> Xquik -> Your Webhook Endpoint

​
Delivery format

Webhook events are delivered as HTTPS POST requests.

​
Headers

Content-Type

application/json. Payloads are always JSON.

User-Agent

xquik-webhooks/1.0 (+https://xquik.com). Identifies Xquik traffic.

X-Xquik-Timestamp

Unix epoch milliseconds. Used in the signing string and for replay window enforcement.

X-Xquik-Nonce

16 random bytes in hex. Reject duplicates within the replay window.

X-Xquik-Signature

sha256=HMAC_HEX_DIGEST. HMAC-SHA256 of <timestamp>.<nonce>.<rawBody>.

​
Payload body

{
  "eventType": "tweet.new",
  "schemaVersion": 1,
  "deliveryId": "502",
  "streamEventId": "9001",
  "occurredAt": "2026-02-24T14:22:00.000Z",
  "username": "elonmusk",
  "data": {
    "id": "1893456789012345678",
    "text": "The future is now.",
    "author": {
      "id": "44196397",
      "userName": "elonmusk",
      "name": "Elon Musk"
    },
    "isRetweet": false,
    "isReply": false,
    "isQuote": false,
    "createdAt": "2026-02-24T14:22:00.000Z"
  }
}

eventType

Type string. Event type, such as tweet.new, tweet.reply, tweet.quote, or tweet.retweet.

schemaVersion

Type number. Webhook payload schema version. Current value is 1.

deliveryId

Type string. Webhook delivery attempt ID. Use this for delivery-log correlation.

streamEventId

Type string. Stored event ID. Use this to match the payload to event history.

occurredAt

Type string. ISO timestamp for when the event occurred.

username

Type string. X username for account monitor events. Omitted for keyword-only monitor events and webhook.test.

query

Type string. Keyword query that matched the event. Present for keyword monitor events.

data

Type object. Raw event object for the monitored tweet activity.
The data field contains the raw tweet object for the monitor event. Fields may vary by tweet type.

​
Event data shapes

Each event type includes a data object. Tweet events contain the raw tweet. The webhook.test event contains a test message and timestamp. The examples below show the most common fields.

​
tweet.new

A new original tweet posted by the monitored account. 
{
  "eventType": "tweet.new",
  "username": "elonmusk",
  "data": {
    "id": "1893456789012345678",
    "text": "The future is now.",
    "author": {
      "id": "44196397",
      "userName": "elonmusk",
      "name": "Elon Musk"
    },
    "isRetweet": false,
    "isReply": false,
    "isQuote": false,
    "createdAt": "2026-02-24T14:22:00.000Z"
  }
}

​
tweet.quote

A quote tweet posted by the monitored account. 
{
  "eventType": "tweet.quote",
  "username": "elonmusk",
  "data": {
    "id": "1893456789012345679",
    "text": "Interesting take on this.",
    "author": {
      "id": "44196397",
      "userName": "elonmusk",
      "name": "Elon Musk"
    },
    "isRetweet": false,
    "isReply": false,
    "isQuote": true,
    "quoted_tweet": {
      "id": "1893400000000000000",
      "text": "Our latest launch was a success.",
      "author": {
        "userName": "SpaceX"
      }
    },
    "createdAt": "2026-02-24T15:10:00.000Z"
  }
}

​
tweet.reply

A reply posted by the monitored account. 
{
  "eventType": "tweet.reply",
  "username": "elonmusk",
  "data": {
    "id": "1893456789012345680",
    "text": "Great question. Working on it.",
    "author": {
      "id": "44196397",
      "userName": "elonmusk",
      "name": "Elon Musk"
    },
    "isRetweet": false,
    "isReply": true,
    "isQuote": false,
    "inReplyToId": "1893411111111111111",
    "createdAt": "2026-02-24T16:30:00.000Z"
  }
}

​
tweet.retweet

A retweet posted by the monitored account. 
{
  "eventType": "tweet.retweet",
  "username": "elonmusk",
  "data": {
    "id": "1893456789012345681",
    "text": "RT @xai: Exciting news today.",
    "author": {
      "id": "44196397",
      "userName": "elonmusk",
      "name": "Elon Musk"
    },
    "isRetweet": true,
    "isReply": false,
    "isQuote": false,
    "createdAt": "2026-02-24T17:00:00.000Z"
  }
}

​
webhook.test

A test payload sent via the Test Webhook endpoint to verify your endpoint is reachable. 
{
  "eventType": "webhook.test",
  "data": {
    "message": "Test delivery from Xquik"
  },
  "timestamp": "2026-02-27T12:00:00.000Z"
}

​
Retry policy

Failed deliveries are retried with exponential backoff (base 1 second, multiplier 2x, max 60 seconds):

Attempts 1-3

Delays: 1 second, 2 seconds, then 4 seconds.

Attempts 4-6

Delays: 8 seconds, 16 seconds, then 32 seconds.

Attempts 7-9

Delay: 60 seconds for each attempt after the cap is reached.

Attempt 10

Final attempt. If it fails, the delivery is marked as exhausted.
After the 10th failed attempt, the delivery is marked as exhausted. A 410 Gone response exhausts the delivery immediately. Check delivery status via the deliveries endpoint.
Retries are processed in batches, so actual delay may be slightly longer than shown.
Terminal failures: Return 410 Gone only when Xquik should stop retrying that delivery. Other non-2xx responses and network failures retry until the delivery is exhausted.

​
Requirements

  • Endpoint must use HTTPS
  • Endpoint must not resolve to a private or internal IP address (localhost, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, 169.254.x.x)
  • Endpoints should respond promptly with a 2xx status code. Non-2xx responses count as failures and trigger retries

​
Where to go next

Webhook API reference

Create, list, update, deactivate, test, and inspect webhook deliveries.

Signature Verification

Verify HMAC-SHA256 signatures and implement idempotency.

Testing Webhooks

Test webhook delivery locally with tunnels and mock payloads.

MCP equivalent

Use xquik.request('/api/v1/webhooks', ...) for create, list, update, delete, and test.

Monitor setup

Create account monitors that emit events for webhook delivery.
Last modified on May 10, 2026