Migration guide
Overview
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.
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).
- Choose the Enterprise or Pro package for Account Activity API access, considering:
- 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.
- Simple webhook server