tweet.new, tweet.reply,
tweet.quote, tweet.retweet, tweet.media, tweet.link, tweet.poll,
tweet.mention, tweet.hashtag, and tweet.longform. There are 11 profile
types. They are profile.avatar.changed, profile.banner.changed,
profile.name.changed, profile.username.changed, profile.bio.changed,
profile.location.changed, profile.url.changed, profile.verified.changed,
profile.protected.changed, profile.pinned_tweet.changed, and
profile.unavailable.changed. The 3 account activity types are tweet.deleted,
broadcast.started, and space.started. The 2 following types are
following.added and following.removed. The 2 follower types are
follower.added and follower.removed. The 2 count types are
profile.followers.changed and profile.following.changed. Keyword monitors
support the 10 tweet types only. The setup returns a monitor ID, webhook ID, and
one-time signing secret. It also returns signed JSON
deliveries. Webhook operations are free. Active monitors cost 30 credits/hour
and include stored events plus webhook delivery.
An added type fires for a follow on top of the account’s X list. A follow
X (Twitter) lists again fires only after the monitor reported its removal. Its data then
carries followKind. refollow means the account followed again. return
means the follow never ended.
Post monitors track 1 X post. Their 10
types are post.reply.new, post.quote.new,
post.likes.changed, post.retweets.changed, post.replies.changed,
post.quotes.changed, post.bookmarks.changed, post.views.changed,
post.edited & post.deleted. Each post event carries postId, postUrl,
authorId & authorUsername.
Have no public endpoint? Stream events over 1
open connection instead, and replay what you missed with Last-Event-ID.
Account or keyword monitor
It outputs a monitor ID, username or query, and selected event types.
It costs 30 credits/hour while active.
Webhook endpoint
It outputs a webhook ID, URL, event types, and one-time
secret.
It is free.Signed delivery
It outputs an HTTPS POST with JSON body and HMAC headers.
The active monitor includes it at no extra cost.
Choose the webhook source
Account activity
Create
POST /monitors when one X account should emit selected tweet and
profile event types. Store monitorId, username, xUserId, and
eventTypes.Keyword matches
Create
POST /monitors/keywords when a query should emit matching tweet
events. Store keywordMonitorId, query, and eventTypes.Post activity
Create
POST /monitors/posts when 1 post should emit replies, quotes,
edits, deletion & metric changes. Store monitorId, postId &
eventTypes.Receiver endpoint
Create
POST /webhooks after the monitor. Store the webhook id, URL,
selected eventTypes, and one-time secret before sending tests.Replay and audit
Use
GET /events for stored monitor events and
GET /webhooks/{id}/deliveries for delivery attempts. Join on
streamEventId.Send events to a Discord channel
Paste a Discord channel webhook URL as the webhook URL. Xquik then sends each event as a Discord message. The message names the account and the event, such as “New post”. It shows the post’s text or the profile change. A link to the post comes with it. Mentions in a post ping no one in your server. Test deliveries reach Discord the same way. Discord can ask Xquik to slow down. The retry then waits as long as Discord asks. The Discord guide sets it up step by step.Send events to a Telegram chat
Call Connect Telegram for a t.me link. Open it and press Start in @XquikBot. Each new post then arrives in that chat as a message. NameeventTypes in the call to add replies, quotes or any other type.
A burst arrives as 1 digest every few seconds. Only the first message rings.
The chat shows in your webhook list as telegram:<chat ID>.
Deliveries, retries, resume and test deliveries work as for any webhook.
Send /stop in the chat to pause alerts, and /status to check them.
The Telegram guide sets it up step by step.Quick setup
Set up webhooks in 3 steps.1
Create a monitor
Choose an account monitor for one X account. Choose a keyword monitor for matching query results.Store the returned monitor
id. Account events include username. Keyword events include query.2
Register a webhook
Provide an HTTPS URL and select which event types to receive. Xquik generates a signing secret. Store it in a secret manager. The API returns it only once.Response.
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.How it works
Delivery format
Xquik sends webhook events as HTTPS POST requests. It sends each monitor event as its own payload. If one active monitor check finds multiple new matching tweets, expect multiple POST requests. You get one per matched tweet event instead of one batched payload.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
Type
string. Event type selected by the source monitor and webhook.schemaVersion
Type
number. Webhook payload schema version. Current value is 1.deliveryId
Type
string. Webhook delivery ID. Every retry reuses it. Store it as the
delivery-level idempotency key and use it for delivery-log correlation.streamEventId
Type
string. Stored monitor event ID. You may need one monitor event
processed once across webhook retries or endpoint changes. If so, store this
ID as the event-level deduplication key.occurredAt
Type
string. ISO timestamp. X’s time of the event when X gives one. A post, a live video & a Space have one. Else the time Xquik saw it. A deleted post, a profile change & a follow list change use that time.monitorId
Type
string. ID of the monitor that produced the event. Account, keyword & post monitors number separately, so read it together with monitorType. Use both to route events when many monitors share 1 webhook URL.monitorName
Type
string. Your monitor label when Xquik created the event. Present when the monitor had a name then. A rename leaves the event unchanged.monitorType
Type
string. account, keyword or post. Matches monitorType on the events API.username
Type
string. Current X (Twitter) username for account monitor events. It follows a username change. Omitted for keyword-only monitor events and webhook.test.xUserId
Type
string. Permanent X (Twitter) user ID of the monitored account, on account monitor events. It stays equal when the account changes its username. Use it to match events from before and after a change.query
Type
string. Keyword query that matched the event. Present for keyword monitor events.postId
Type
string. ID of the monitored post. Present for post monitor events.postUrl
Type
string. Link to the monitored post. Present for post monitor events.authorId
Type
string. Permanent X (Twitter) user ID of the monitored post’s author. Present for post monitor events.authorUsername
Type
string. Username of the monitored post’s author. Present for post monitor events.data
Type
object. Raw event object for the monitored tweet activity.Post fields match REST responses. Profiles use
username and verified for the displayed badge.
Legacy userName remains available. rawVerified preserves the original X flag.
The verified field now includes blue verification. Card, reaction, quote & repost profiles use these fields.
Stored posts gain these fields when their source fields are available. Incomplete legacy posts remain readable.Receiver storage row
After signature verification succeeds, store a compact receiver row. Then hand the event to workers. UsedeliveryId for delivery-level retries and streamEventId for event-level processing. Never put endpoint signing values or the raw request body in shared incident rows. Leave out the raw signature and full headers too.Tweet & profile event shapes
Each event type includesdata. Tweet events contain public post fields and retained legacy fields.
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.tweet.quote
A quote tweet posted by the monitored account.tweet.reply
A reply posted by the monitored account.tweet.retweet
A retweet posted by the monitored account.webhook.test
A test payload that the Test Webhook endpoint sends. It checks that your endpoint is reachable.Post event shapes
Post events carrymonitorType post and the tracked post’s fields.
post.reply.new & post.quote.new carry the reply or quote as data, like
tweet.new.post.likes.changed
Each metric’s changed event fires at most once a minute. It covers the whole
change since the last one. The other 5 metric events use the same data.post.edited
The author edited the post. versionId is the newest version’s ID.post.deleted
The post was deleted. text is the last text the monitor saw.Delivery order
Deliveries can arrive in any order. Xquik sends up to 20 at once to 1 endpoint. Retries can come after newer events. Order events byoccurredAt, then
streamEventId.
A 429, 503 or timeout limits Xquik to 8 at once. The limit holds until 1
minute passes without one.Retry policy
Return2xx within 10 seconds for every delivery, even one you skip. Any other
status, a redirect, a timeout, or a network error is a failure. 410 Gone is a
normal failure.
Xquik retries a failed delivery until your endpoint returns 2xx. Each
delivery gets 7 days from the time Xquik queues it. A delivery still failing
after 7 days ends as exhausted. Xquik never pauses or turns off your webhook.Failing endpoint
After a failed delivery, Xquik treats your endpoint as failing. It retries 1
waiting delivery at a time to check the endpoint. This is a real delivery,
not a
webhook.test. Checks start 2 seconds apart and slow to 1 every 15
minutes. New deliveries wait as pending until a check succeeds.Recovery
When a check succeeds, Xquik starts sending
pending deliveries at once.
A delivery your endpoint rejected can wait until its 7 days end.
Resume Webhook sends it at once.1 rejected delivery
A new event may not arrive within 2 seconds of a failure. In that case,
Xquik retries the rejected delivery at the next check. New events wait for
that check, up to 15 minutes. See the table below.
Quiet endpoint
A rejected delivery keeps failing checks while no new events arrive. After
about 2 quiet days, the webhook shows
needs_attention. Delivery continues.No retry comes later than 7 days after Xquik queued the delivery. Retries can
arrive a little later than listed.
Pause or delete a webhook
Pause the webhook with Update Webhook, or delete it. Xquik holds the deliveries that were waiting. Each one showsexhausted once its 7 days end. A paused monitor holds its deliveries the same
way.Events expire 30 days after Xquik creates them. An event whose delivery ended
as exhausted stays 30 days after that delivery ended.
Resume Webhook sends a signed test first. Then
it starts sending held deliveries at once.A paused webhook gets no new deliveries. Use stored event pages to catch up.
Deleting a monitor removes its waiting deliveries.Check delivery status
List Deliveries shows each delivery’sstatus, which is pending, delivered, failed, or exhausted.
exhausted means 7 days passed without a 2xx, and lastError says why.
attempts counts the tries so far. A retry reuses the same deliveryId, so store it and skip
repeats.List Webhooks shows deliveryStatus and
consecutiveFailures. needs_attention means 200 failed checks in a row. That
takes about 2 days. Xquik keeps retrying.When deliveries fail
- Fix your endpoint so it returns
2xxwithin 10 seconds. - Call Resume Webhook. It sends a signed test first.
- When the test passes, Xquik starts sending waiting and rejected deliveries at once.
Backfill after a receiver outage
Xquik resends failed deliveries after your receiver recovers. Use this handoff when your systems lost work or the webhook was paused. Fix the receiver first. Then use delivery rows and stored event pages to rebuild downstream work.nextCursor after every event page. Reprocess only events your receiver
never stored. Skip repeats by streamEventId, since Xquik also resends failed
deliveries. Events from a pause may never reach the webhook, so page them here.
Scope event pages when the source is known. Use monitorId for account monitors
or keywordMonitorId for keyword monitors. Omit both only for all-monitor
replay.Troubleshoot a delivery
Use this handoff when a receiver fails a signed test or keeps failing deliveries.Signed receiver test
Run Test Webhook after changing endpoint
code, secrets, firewall rules, or queue routing. Treat
success: true
with a 2xx statusCode as receiver proof.Signature and IDs
Verify
X-Xquik-Signature, X-Xquik-Timestamp, and X-Xquik-Nonce on
the raw request body. webhook.test omits deliveryId and streamEventId,
while production deliveries include both IDs.Delivery triage
Check List Deliveries for
status,
attempts, lastStatusCode, lastError, createdAt, and
deliveredAt. Act on failed, wait on pending, and ignore
delivered. exhausted means 7 days passed without a 2xx.Needs attention
needs_attention does not stop delivery. Fix the receiver, then call
Resume Webhook. It starts sending waiting
deliveries at once.Event context
Join
streamEventId to Get Event when the
receiver owner needs what triggered the delivery. That means the original
monitor event, tweet fields, username, or keyword query.Requirements
- The endpoint must use HTTPS
- The endpoint must not resolve to a private or internal IP address. That rules out localhost, 10.x.x.x, 172.16-31.x.x, 192.168.x.x and 169.254.x.x
- Endpoints must return
2xxwithin 10 seconds
Where to go next
Webhook API reference
Create, list, update, deactivate, test, resume, 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.
Keyword monitor setup
Create keyword monitors that emit matching tweet events for webhook delivery.