Skip to main content
POST
Twitter webhook API | create signed endpoint
Free - 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 events will be delivered. HTTP URLs are rejected. 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) are also rejected.
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.
webhook.test is sent only by the Test Webhook endpoint. It is not a subscribable eventTypes value.

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; webhook delivery is included with monitor billing. Store these fields immediately 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; 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 configuration drift 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 and streamEventId when one monitor event must be processed 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 asynchronously. 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 is subscribed to.
string
HMAC signing secret (64-character hex string). Store securely. Returned only at creation time.
string
ISO 8601 creation timestamp.
The secret is returned only once. Store it securely. You need it to verify webhook signatures. It cannot be retrieved again.

401 Unauthenticated

Missing or invalid API key / 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 supports dual authentication: API key (x-api-key header) or session cookie from the dashboard.Next steps. List Webhooks · Signature Verification · Webhooks Overview