Skip to main content
POST
Twitter webhook API to create a signed endpoint
Free. This endpoint does not consume credits.

Headers

string
required
Your API key. Session cookie authentication is also supported.
string
required
Must be application/json.

Body

string
required
HTTPS endpoint URL where Xquik delivers events. Xquik rejects HTTP URLs. It also rejects URLs resolving to private or internal IP addresses (localhost, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, 169.254.x.x).
string[]
required
Array of event types to subscribe to. At least 1 required. Use any valid account monitor event type listed below. Keyword monitors emit only tweet.* event types. Account monitors can emit both tweet.* and profile.* event types.

Valid event types

Valid types: tweet.new, tweet.quote, tweet.reply, tweet.retweet, tweet.media, tweet.link, tweet.poll, tweet.mention, tweet.hashtag, tweet.longform, 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, profile.unavailable.changed.

tweet.new

Original tweet from an account monitor or matching keyword monitor. Use for new posts that are not replies, quotes, or retweets.

tweet.quote

Quote tweet from an account monitor or matching keyword monitor. Pair with monitors that include tweet.quote.

tweet.reply

Reply from an account monitor or matching keyword monitor. Pair with monitors that include tweet.reply.

tweet.retweet

Retweet from an account monitor or matching keyword monitor. Pair with monitors that include tweet.retweet.
Only the Test Webhook endpoint sends webhook.test. You cannot subscribe to it in eventTypes.

Integration handoff

Use this endpoint after creating an account monitor with POST /monitors or a keyword monitor with POST /monitors/keywords. The webhook stores the HTTPS endpoint and event-type filter. Active monitors produce the events. Monitor billing includes webhook delivery. Store these fields right after creation:

Webhook ID

Store id for POST /webhooks/{id}/test, updates, deletes, and delivery lookups.

Delivery URL

Store url to audit which queue, CRM, warehouse, or app endpoint receives monitor events.

Event filter

Store eventTypes, and keep the webhook filter aligned with the account or keyword monitor event types.

Signing secret

Store secret once and use it to verify X-Xquik-Signature on the raw request body.

Created at

Store createdAt for audit logs and later configuration checks.

Delivery payload

Expect HTTPS POST bodies with eventType, schemaVersion, deliveryId, streamEventId, occurredAt, data, plus username for account monitor events or query for keyword monitor events.
Every delivery includes X-Xquik-Signature, X-Xquik-Timestamp, and X-Xquik-Nonce headers. Use deliveryId as the per-endpoint idempotency key. Use streamEventId when you must process one monitor event once across retries or endpoints. Test the endpoint with POST /webhooks/{id}/test before routing production events. Return a 2xx response within 10 seconds, then process slow Slack, CRM, warehouse, or queue work afterward. Use Signature Verification to validate the raw request body before processing.

Response

201 Created

string
Unique webhook identifier.
string
The registered delivery endpoint.
string[]
Event types this webhook subscribes to.
string
HMAC signing secret (64-character hex string). Xquik returns it only at creation. Store it in a secret manager.
string
ISO 8601 creation timestamp.
The API returns secret once. Store it in a secret manager. You need it to verify webhook signatures. You cannot retrieve it again.

401 Unauthenticated

Missing or invalid API key or session cookie.

400 Invalid input

Invalid URL (must be HTTPS) or empty eventTypes array.

429 Rate limited

Too many requests. Wait for the Retry-After header before retrying.
This endpoint accepts 2 auth methods. Send an API key in the x-api-key header or a session cookie from the dashboard.Next steps. List Webhooks · Signature Verification · Webhooks Overview