Skip to main content
X (Twitter) webhooks let agents respond to account activity events like tweets, likes, follows, and direct messages via the Account Activity API.

​
Filter Fields (all optional)

FieldTypeDescription
eventsstring[]Twitter event types: tweet_create_events, tweet_delete_events, favorite_events, follow_events, unfollow_events, block_events, unblock_events, mute_events, unmute_events, direct_message_events, direct_message_indicate_typing_events, direct_message_mark_read_events
usersstring[]Only trigger for these subscribed user IDs (for_user_id values)

​
Setup

  1. In the X Developer Portal, create or open your app
  2. Under Keys and tokens, note your Consumer Key and Consumer Secret
  3. Generate an Access Token and Access Token Secret for your bot user account
  4. Run al doctor — it will prompt for all four values plus your Bearer Token
  5. Register your webhook URL with the Account Activity API: https://your-server:8080/webhooks/twitter
  6. The gateway handles the CRC challenge-response handshake automatically using the Consumer Secret
  7. On startup, the gateway automatically subscribes your bot user if Access Token credentials are configured

​
Credentials

The x_twitter_api credential has five fields:
FieldRequiredDescription
consumer_keyYesOAuth 1.0a Consumer Key
consumer_secretYesOAuth 1.0a Consumer Secret (used for CRC and HMAC validation)
bearer_tokenYesApp-Only Bearer Token (used for API v2 validation)
access_tokenNoOAuth 1.0a Access Token for the bot user (enables auto-subscribe)
access_token_secretNoOAuth 1.0a Access Token Secret for the bot user (enables auto-subscribe)
When access_token and access_token_secret are provided, the gateway will automatically check the webhook registration status and subscribe the bot user to the Account Activity API on startup.

​
CRC Challenge

The Twitter provider automatically handles CRC (Challenge-Response Check) validation. When Twitter sends a GET request with a crc_token query parameter, the gateway responds with the correct HMAC-SHA256 response token. No manual setup is needed.

​
Example Configuration

# In project config.toml
[webhooks.my-twitter]
type = "twitter"
credential = "MyXApp"

# In agents/<name>/config.toml
[[webhooks]]
source = "my-twitter"
events = ["tweet_create_events", "favorite_events", "direct_message_events"]
users = ["123456789"]