Subscribe to account activity
Premium Account Activity API¶
There are two pricing options available under the Premium tier of the Account Activity API:
- Free (Sandbox) - supports 1 environment/webhook.
- Paid - supports up to 2 environments/webhooks.
Please keep the above in mind as you navigate this page.
POST account_activity/all/:env_name/webhooks¶
Registers a webhook URL for all event types. The URL will be validated via CRC request before saving. In case the validation failed, returns comprehensive error message to the requester.
Resource URL¶
https://api.twitter.com/1.1/account_activity/all/:env_name/webhooks.json
Resource Information¶
Response Format | JSON |
Requires Authentication | Yes (user context - all consumer and access tokens) |
Rate Limited | Yes |
Requests / 15-min window (user auth) | 15 |
Parameters¶
url (required) | Encoded URL for the callback endpoint. |
Example Request¶
$ curl --request POST
--url 'https://api.twitter.com/1.1/account_activity/all/:ENV_NAME/webhooks.json?url=https%3A%2F%2Fyour_domain.com%2Fwebhook%2Ftwitter'
--header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'
HTTP Responses¶
HTTP Code | Message |
---|---|
200 | Webhook URL is registered to the provided application |
403 | There is an error with your request. See error messages section below. |
Example Response - Success¶
HTTP 200
{
"id": "1234567890",
"url": "https://your_domain.com/webhook/twitter",
"valid": true,
"created_at": "2016-06-02T23:54:02Z"
}
Error Messages¶
Code | Message |
---|---|
214 | Webhook URL does not meet the requirements. |
214 | Too many resources already created. |
214 | Webhook URL does not meet the requirements. Invalid CRC token or json response format. |
214 | High latency on CRC GET request. Your webhook should respond in less than 3 seconds. |
214 | Non-200 response code during CRC GET request (i.e. 404, 500, etc). |
HTTP 403
{
"errors": [
{
"code": 214,
"message": "Too many resources already created."
}
]
}
GET account_activity/all/webhooks¶
Returns all environments, webhook URLs and their statuses for the authenticating app. Currently, only one webhook URL can be registered to each environment.
We mark a URL as invalid if it fails the daily validation check. In order to re-enable the URL, call the update endpoint.
Alternatively, this endpoint can be used with an environment name to only return webhook URLS for the given environment: GET account_activity/all/:env_name/webhooks (see second example)
Resource URL¶
https://api.twitter.com/1.1/account_activity/all/webhooks.json
Resource Information¶
Response Format | JSON |
Requires Authentication | Yes (application only - bearer token) |
Rate Limited | Yes |
Requests / 15-min window (application-auth) | 15 |
Example Request¶
$ curl --request GET
--url https://api.twitter.com/1.1/account_activity/all/webhooks.json
--header 'authorization: Bearer TOKEN'
Example Response¶
HTTP 200 OK
{
"environments": [
{
"environment_name": "env-beta",
"webhooks": [
{
"id": "1234567890",
"url": "https://your_domain.com/webhook/twitter",
"valid": true,
"created_at": "2017-06-02T23:54:02Z"
}
]
}
]
}
Alternative w/env_name Resource URL¶
https://api.twitter.com/1.1/account_activity/all/:env_name/webhooks
Resource Information¶
Response Format | JSON |
Requires Authentication | Yes (application only - bearer token) |
Rate Limited | Yes |
Requests / 15-min window (application-auth) | 15 |
Example Request¶
$ curl --request GET
--url https://api.twitter.com/1.1/account_activity/all/:env_name/webhooks.json
--header 'authorization: Bearer TOKEN'
Example Response¶
HTTP 200 OK
[
{
"id": "1234567890",
"url": "https://your_domain.com/webhook/twitter",
"valid": true,
"created_at": "2016-06-02T23:54:02Z"
}
]
Error Messages¶
Code | Message |
---|---|
99 | You don’t have access to this resource. |
PUT account_activity/all/:env_name/webhooks/:webhook_id¶
Triggers the challenge response check (CRC) for the given enviroments webhook for all activites.
If the check is successful, returns 204 and reenables the webhook by setting its status to valid
.
Resource URL¶
https://api.twitter.com/1.1/account_activity/all/:env_name/webhooks/:webhook_id.json
Resource Information¶
Response Format | JSON |
Requires Authentication | Yes (user context - all consumer and access tokens) |
Rate Limited | Yes |
Requests / 15-min window (user auth) | 15 |
Example Request¶
$curl --request PUT
--url https://api.twitter.com/1.1/account_activity/all/:ENV_NAME/webhooks/:WEBHOOK_ID.json
--header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'
Response¶
HTTP 204 NO CONTENT
Error Messages¶
Code | Message |
---|---|
214 | Webhook URL does not meet the requirements. |
214 | Webhook URL does not meet the requirements. Invalid CRC token or json response format. |
214 | High latency on CRC GET request. Your webhook should respond in less than 3 seconds. |
214 | Non-200 response code during CRC GET request (i.e. 404, 500, etc). |
POST account_activity/all/:env_name/subscriptions¶
Subscribes the provided application to all events for the provided environment for all message types. After activation, all events for the requesting user will be sent to the application’s webhook via POST request.
Subscriptions are limited to a maximum of 15 unique users per application in the free (sandbox) tier.
Resource URL¶
https://api.twitter.com/1.1/account_activity/all/:env_name/subscriptions.json
Resource Information¶
Response Format | JSON |
Requires Authentication | Yes (3-legged OAuth - Whitelisted consumer key and subscribing user’s access token) |
Rate Limited | Yes |
Requests / 15-min window (user auth) | 500 |
Example Request¶
$ curl --request POST
--url https://api.twitter.com/1.1/account_activity/all/:ENV_NAME/subscriptions.json
--header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBING_USER'S_ACCESS_TOKEN", oauth_version="1.0"'
Example Response - Success¶
HTTP 204 NO CONTENT
Error Messages¶
Code | Message |
---|---|
348 | Client application is not permitted to access this user’s webhook subscriptions. |
GET account_activity/subscriptions/count¶
Returns the count of subscriptions that are currently active on your account for all activities. Note that the /count endpoint requires application-only OAuth, so that you should make requests using a bearer token instead of user context.
Resource URL¶
https://api.twitter.com/1.1/account_activity/subscriptions/count.json
Resource Information¶
Response Format | HTTP response code |
Requires Authentication | Yes (application only - bearer token) |
Rate Limited | Yes |
Requests / 15-min window (application-auth) | 15 |
HTTP Response Codes¶
Code | Message |
200 | Success. A count of subscriptions for the requested webhook will be returned. |
401 | Your application does not have permission to view subscriptions for the specified webhook. |
Example Request¶
$ curl --request GET
--url https://api.twitter.com/1.1/account_activity/subscriptions/count.json
--header 'authorization: Bearer TOKEN'
Example Response - Success¶
HTTP 200
{
"account_name: "test-account",
"subscriptions_count_all": "2",
"subscriptions_count_direct_messages": "1"
}
Error Messages¶
Code | Message |
---|---|
32 | Could not authenticate you. |
HTTP 401
{
"errors": [
{
"code": 32,
"message": "Could not authenticate you."
}
]
}
GET account_activity/all/:env_name/subscriptions¶
Provides a way to determine if a webhook configuration is subscribed to the provided user’s events. If the provided user context has an active subscription with provided application, returns 204 OK. If the response code is not 204, then the user does not have an active subscription. See HTTP Response code and error messages below for details.
Resource URL¶
https://api.twitter.com/1.1/account_activity/all/:env_name/subscriptions.json
Resource Information¶
Response Format | JSON |
Requires Authentication | Yes (3-legged OAuth - Whitelisted consumer key and subscribing user’s access token) |
Rate Limited | Yes |
Requests / 15-min window (user auth) | 500 |
Example Request¶
$ curl --request GET
--url https://api.twitter.com/1.1/account_activity/all/:ENV_NAME/subscriptions.json
--header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBING_USER'S_ACCESS_TOKEN", oauth_version="1.0"'
Example Response - Success¶
HTTP 204 NO CONTENT
GET account_activity/all/:env_name/subscriptions/list¶
Returns a list of the current All Activity type subscriptions. Note that the /list endpoint requires application-only OAuth, so requests should be made using a bearer token instead of user context.
Resource URL¶
https://api.twitter.com/1.1/account_activity/all/:env_name/subscriptions/list.json
Resource Information¶
Response Format | HTTP response code |
Requires Authentication | Yes (application only - bearer token) |
Rate Limited | Yes |
Requests / 15-min window (application-auth) | 50 |
HTTP Response Codes¶
Code | Message |
---|---|
200 | Success. A list of subscriptions for the requested webhook will be returned. |
401 | Your application does not have permission to view subscriptions for the specified webhook. |
Example Request¶
$ curl --request GET
--url https://api.twitter.com/1.1/account_activity/all/:ENV_NAME/subscriptions/list.json
--header 'authorization: Bearer TOKEN'
Example Response - Success¶
HTTP 200
{
"environment": "appname",
"application_id": "13090192",
"subscriptions": [
{
"user_id": "3001969357"
}
]
}
Error Messages¶
Code | Message |
---|---|
32 | Could not authenticate you. |
HTTP 401
{
"errors": [
{
"code": 32,
"message": "Could not authenticate you."
}
]
}
DELETE account_activity/all/:env_name/webhooks/:webhook_id¶
Removes the webhook from the provided application’s all activities configuration. The webhook ID can be accessed by making a call to GET /1.1/account_activity/all/webhooks.
Resource URL¶
https://api.twitter.com/1.1/account_activity/all/:env_name/webhooks/:webhook_id.json
Resource Information¶
Response Format | JSON |
Requires Authentication | Yes (user context - all consumer and access tokens) |
Rate Limited | Yes |
Requests / 15-min window (user auth) | 15 |
Example Request¶
$ curl --request DELETE
--url https://api.twitter.com/1.1/account_activity/all/:ENV_NAME/webhooks/:WEBHOOK_ID.json
--header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'
Response¶
HTTP 204 NO CONTENT
DELETE /account_activity/all/:env_name/subscriptions¶
Deactivates subscription(s) for the provided user context and application for all activities. After deactivation, all events for the requesting user will no longer be sent to the webhook URL.
Resource URL¶
https://api.twitter.com/1.1/account_activity/all/:env_name/subscriptions.json
Resource Information¶
Response Format | JSON |
Requires Authentication | Yes (3-legged OAuth - Whitelisted consumer key and subscribed user’s access token) |
Rate Limited | Yes |
Requests / 15-min window (user auth) | 500 |
Example Request¶
$ curl --request DELETE
--url https://api.twitter.com/1.1/account_activity/all/:ENV_NAME/subscriptions.json
--header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBED_USER'S_ACCESS_TOKEN", oauth_version="1.0"'
Response¶
HTTP 204 NO CONTENT