v2 Account Activity API Migration Guide

This guide helps you migrate from the legacy Enterprise Account Activity API to the V2 Account Activity API. The core functionality remains the same, but endpoint structures and authentication methods have been updated for consistency with X API v2.

Summary of Changes

• API Format: Endpoints use the /2/account_activity/ base path instead of /1.1/account_activity/.
• Webhook Management: Webhook creation, listing, validation (CRC), and deletion are handled by the V2 Webhooks API.
• Authentication: V2 endpoints require either:
  • OAuthUser (3-legged OAuth) for user-specific actions (e.g., subscribing a user).
  • OAuth2 App Only (Bearer Token) for app-level actions (e.g., listing/deleting subscriptions).
  • V1.1 used varying requirements, often OAuth 1.0a.
• Endpoint Mapping:

V1.1 Endpoint	V2 Equivalent / Action	Notes
POST /1.1/account_activity/webhooks.json?url=<URL>	POST /2/webhooks	Docs. Requires OAuth2AppOnly.
GET /1.1/account_activity/webhooks.json	GET /2/webhooks	Docs. Requires OAuth2AppOnly.
PUT /1.1/account_activity/webhooks/:webhook_id.json	PUT /2/webhooks/:webhook_id	Triggers CRC. Docs. Requires OAuth2AppOnly.
DELETE /1.1/account_activity/webhooks/:webhook_id.json	DELETE /2/webhooks/:webhook_id	Docs. Requires OAuth2AppOnly.
POST /1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json	POST /2/account_activity/webhooks/:webhook_id/subscriptions/all	Requires OAuthUser.
GET /1.1/account_activity/subscriptions/count.json	GET /2/account_activity/subscriptions/count	Requires OAuth2AppOnly.
GET /1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json	GET /2/account_activity/webhooks/:webhook_id/subscriptions/all	Requires OAuthUser.
GET /1.1/account_activity/webhooks/:webhook_id/subscriptions/all/list.json	GET /2/account_activity/webhooks/:webhook_id/subscriptions/all/list	Requires OAuth2AppOnly.
DELETE /1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all	DELETE /2/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all	Requires OAuth2AppOnly.
DELETE /1.1/account_activity/webhooks/:webhook_id/subscriptions/all	Deprecated / No Direct Equivalent	Use individual deletes or remove the webhook via DELETE /2/webhooks/:webhook_id.

• Response Formats: Review the success and error response structures in the AAAPI documentation.

When migrating, update your code to use the new base paths, adjust authentication flows, and manage webhooks using the V2 Webhooks API.

How to Migrate

• Decide on a Package:
  • Choose the Enterprise or Pro package for Account Activity API access, considering:
    • Number of webhooks needed.
    • Current/projected subscriptions or authorized users.
    • Number of X client applications.
    • Desired support level (forum vs. managed enterprise 1:1 support).
    • Pricing details (contact sales for Enterprise).
• Update Your Authentication to OAuth 2.0:
  • Ensure your X App has “Read, Write, and Access Direct Messages” permissions.
  • Update to OAuth 2.0 for V2 endpoints. Re-authorize users if scopes have changed.
  • Use the Developer Portal to manage:
    • OAuth 2.0 Access Token.
    • Client ID and Client Secret.
• Verify or Reconfigure Your Webhook:
  • Use your existing webhook URL or set up a new one (e.g., https://your\_domain.com/webhook/twitter).
  • Follow the V2 Webhooks API documentation to register and manage your webhook.
• Sample Apps:
  • Simple webhook server
    • A single python script that shows you how to respond to the CRC check and accept POST events.
  • Account Activity API sample dashboard
    • A web app written with bun.sh that allows you to manage webhooks, subscriptions, and receive live events directly in the app.