Manage webhooks and subscribed users

⏱ 10 min read

The enterprise Account Activity API provides you webhook-based JSON messages any time there are events associated with Twitter accounts subscribed to your service. Twitter delivers those activities to your whitelisted webhook. In the following steps, you will learn how to manage webhooks and subscribed users.

You will learn how to register, view, and remove, both webhooks and subscribed users. We'll be using simple cURL commands to make requests to the various API endpoints. cURL is a command-line tool for getting or sending requests using the URL syntax.

You will need:

 

Before you get started, we recommend you check out our Github repo here that provides a sample web app and helper scripts to get started with Twitter's Account Activity API

 

Managing a webhook:


Using a webhook provides you the ability to subscribe to realtime activities related to a user account through a single connection. 

 

  • Adding a webhook
  • Viewing a webhook
  • Removing a webhook

Let’s begin with registering a new webhook URL for the given application context.

 

The URL will be validated via a CRC request before saving. Once you've registered a webhook, make sure to document the webhook ID as you will need it later on.

 

Copy the following cURL request into your command line after making changes to the following:

 

  • URL <URL> e.g. https://yourdomain.com/webhooks/twitter/
  • Consumer key <CONSUMER_KEY> e.g. xvz1evFS4wEEPTGEFPHBog
  • Access token <ACCESS_TOKEN> e.g.  370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb
  curl --request POST --url 'https://api.twitter.com/1.1/account_activity/webhooks.json?url=<URL>' --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"'

We will run the following command to returns all registered webhook URLs and their statuses for the given application.

 

Copy the following cURL request into your command line after making changes to the following:

 

  • Bearer token <BEARER_TOKEN> e.g. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...
  curl --request GET --url https://api.twitter.com/1.1/account_activity/webhooks.json --header 'authorization: Bearer <BEARER_TOKEN>'

To remove a webhook from the provided application's configuration, copy the following cURL request into your command line after making changes to the following:

 

  • Webhook ID <:WEBHOOK_ID> e.g. 1234567890
  • Consumer key <CONSUMER_KEY> e.g. xvz1evFS4wEEPTGEFPHBog
  • Access token <ACCESS_TOKEN> e.g.  370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb
  curl --request DELETE --url https://api.twitter.com/1.1/account_activity/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"'

Managing subscribed users:


Once you've registered a Webhook, you can add a subscribed user to the Account Activity API to begin receiving their account activities.

 

  • Adding a subscription
  • Viewing subscriptions
  • Removing a subscription

We'll begin with subscribing a user so you recieve all event types.

 

Copy the following cURL request into your command line after making changes to the following:

 

  • Webhook ID <:WEBHOOK_ID> e.g. 1234567890
  • Whitelisted consumer key name <WHITELISTED_CONSUMER_KEY> e.g. xvz1evFS4wEEPTGEFPHBog
  • Subscribing user's access token <SUBSCRIBING_USER'S_ACCESS_TOKEN> e.g. 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb
  curl --request POST --url https://api.twitter.com/1.1/account_activity/webhooks/<:WEBHOOK_ID>/subscriptions/all.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"'

To view a list of all activity type subscriptions for a specified webhook, copy the following cURL request into your command line after making changes to the following:

 

  • Webhook ID <:WEBHOOK_ID> e.g. 1234567890
  • Bearer token <BEARER_TOKEN> e.g. AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...
  curl --request GET --url https://api.twitter.com/1.1/account_activity/webhooks/<:WEBHOOK_ID>/subscriptions/all/list.json --header 'authorization: Bearer <BEARER_TOKEN>'

After deactivation, all events for the requesting user will no longer be sent to the webhook URL.

 

To deactivate a subscription from the provided user context and application, copy the following cURL request into your command line after making changes to the following:

 

  • Webhook ID <:WEBHOOK_ID> e.g. 1234567890
  • Whitelisted consumer key <WHITELISTED_CONSUMER_KEY> e.g. xvz1evFS4wEEPTGEFPHBog
  • Subscribing user's access token <SUBSCRIBING_USER'S_ACCESS_TOKEN> e.g. 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb
  curl --request DELETE --url https://api.twitter.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.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"'