Webhooks - OmniX

Instead of polling for new activity, register a URL you control and OmniX POSTs events to it the moment they happen on the connected X account — direct messages, plus mentions, replies, likes and follows.

Register your URL with POST /webhooks.
Confirm ownership with a one-time CRC handshake.
Receive typed, signed events at your URL as activity happens.

What you provide

auth_token

The X account whose activity you want delivered.

encryption_code

Supply it to receive DM events. Omit it and you still get tweet activity (mentions/replies/likes/follows).

secret

Returned once on create (or supply your own). Used to answer CRC and to verify the signature on every delivery.

POST /webhooks (create) also accepts an optional proxy. It is stored with the webhook, and the background poller routes all of that account’s X traffic through it for the lifetime of the webhook. See Authentication.

1. CRC — proving you own the URL

Before any events are delivered, your URL receives a GET with a crc_token query param. Your endpoint must reply within 10s with:

{ "response_token": "sha256=<base64( HMAC-SHA256(secret, crc_token) )>" }

A webhook only becomes valid:true and starts receiving events once it passes CRC.

The secret is generated by us and returned once in the Create response — so the first create can’t pass CRC until your receiver knows it. Either supply your own secret in the Create body (so CRC passes immediately), or create first, configure your receiver with the returned secret, then call Validate.

2. Verifying each delivery

Every event is POSTed with this header:

x-twitter-webhooks-signature: sha256=<base64( HMAC-SHA256(secret, rawRequestBody) )>

Recompute it over the raw body with your secret and compare — if it matches, the event genuinely came from OmniX.

A minimal Node receiver (CRC + signature check) is only a few lines — see the Quickstart snippet below.

3. The events you receive

Each delivery is one JSON object with a type.

`type`	When
`message.received` / `message.sent`	a DM is received / sent
`message.edited`	a DM is edited
`message.deleted`	a DM is deleted
`message.reactionAdded` / `message.reactionRemoved`	a reaction changes on a DM
`tweet.mention`	someone @mentions the account
`tweet.reply`	someone replies to its tweet
`tweet.quote`	someone quote-tweets it
`tweet.like`	someone likes its tweet
`tweet.retweet`	someone retweets it
`user.follow`	someone follows it

Tweet events fire on incoming activity (someone acts on your account). Your own outgoing actions — e.g. following someone yourself — do not produce an event.

Example payloads

message.received

{
  "type": "message.received",
  "conversation_id": "1000000000000000001:2000000000000000002",
  "message_id": "a1b2c3d4-0000-0000-0000-000000000000",
  "seq_id": "3000000000000000000",
  "sender_id": "2000000000000000002",
  "from_me": false,
  "text": "hey there",
  "created_at": "2026-06-14T12:24:52.899000Z"
}

tweet.mention

{
  "type": "tweet.mention",
  "tweet_id": "4000000000000000000",
  "text": "@your_handle check this out",
  "author_id": "5000000000000000000",
  "author_screen_name": "someone",
  "author_name": "Someone"
}

user.follow

{
  "type": "user.follow",
  "actor_ids": ["5000000000000000000"],
  "actor_screen_names": ["someone"]
}

Typical flow

Create

POST /webhooks with your url, auth_token, and (for DMs) encryption_code. Save the returned secret. Supply your own secret to pass CRC on this call.

Validate (if needed)

If you didn’t pre-share the secret, configure your receiver with the returned secret and call PUT /webhooks/{id} to re-run CRC until valid:true.

Receive

Handle POSTs at your URL — verify x-twitter-webhooks-signature, then switch on type. Respond 200 within 10s.

Recover (optional)

Missed deliveries? POST /webhooks/replay re-sends the last 24h of events.

Stop

DELETE /webhooks/{id} to stop delivery.

Pricing

Management calls are billed per call: $0.0025** for create / list / validate / delete, **$ 0.005 for replay. (Event deliveries themselves aren’t charged per event.)

Try it from the API Reference → Webhooks pages. For local testing you can register a http://localhost URL (no public tunnel needed).

​What you provide

auth_token

encryption_code

secret

​1. CRC — proving you own the URL

​2. Verifying each delivery

​3. The events you receive

​Example payloads

​Typical flow

​Pricing

What you provide

1. CRC — proving you own the URL

2. Verifying each delivery

3. The events you receive

Example payloads

Typical flow

Pricing