Getting started with webhooks

Premium

Enterprise

The Account Activity API is a webhook-based API that sends account events to a web app you develop, deploy and host. 

There are several 'plumbing' details that need attention before you can start receiving webhook events in your event consumer application. As described below, you will need to create a Twitter app, obtain Account Activity API access, and develop a web app that consumes webhook events. 

 

1. Create a Twitter app.

  • Create an app at apps.twitter.com. If you are creating the app on behalf of your company, it is recommended you create the app with a corporate Twitter account.
  • Enable “Read, Write and Access direct messages” on the permissions tab of your app page.
  • On the "Keys and Access Tokens" tab, take note of your app's Consumer Key (API Key) and Consumer Token (API Secret).
  • On the same tab, generate your app's Access Token and Access Token Secret. You will need these Access Tokens to register your webhook URL, which is where Twitter will send account events.
  • If you are unfamiliar with Twitter Sign-in and how user contexts work with the Twitter API review Obtaining Access Tokens. As you add accounts for which to receive events, you will subscribe them using that account's access tokens.
  • Take note of your app's numeric ID, as seen in its https://apps.twitter.com/app/<app ID> URL. When you apply for Account Activity API access, you'll need this app ID.
     

2. Get Account Activity API access

After creating a Twitter app, the next step is applying for Account Activity API access. 

Premium

To access the Sandbox or Paid Premium Account Activity API tiers, you need to set up a developer account. If you have not applied for a developer account yet, please do so at the following link:


Once you have a developer account, then you are ready to set up your access to the Premium Account Activity API. You will need a registered 

  1. Login and navigate to the Dev Environments page. 
  2. Click 'Set up dev environment,' name your environment, and specify a Twitter app ID for the environment. The environment name you chose will replace the :env_name token in our example premium endpoint URLs. For example, if you use the 'prod' environment name, your URL pattern would be  https://api.twitter.com/1.1/account_activity/all/prod/webhooks.

     

Enterprise

Those needing enterprise level access to more than 250 account subscriptions and 3+ webhooks will need to submit an application at the following link:

 

3. Develop webhook consumer app

Once you have received Account Activity API access, you need to develop, deploy and host a web app that will receive Twitter webhook events. 

  • Create a web app with a URL to use as your webhook to receive events. This is the endpoint deployed on your server to listen for incoming Twitter webhook events. 
    • The URI path is completely up to you. This example would be valid: https://mydomain.com/service/listen
    • If you are listening for webhooks from a variety of sources, a common pattern is: https://mydomain.com/webhook/twitter
    • Note that the specified URL can not include a port specification (https://mydomain.com:5000/NoWorkie).
  • As described in our Securing Webhooks guide, a first step is writing code that receives a Twitter Challenge Response Check (CRC) GET request and responds with a properly formatted JSON response. 
  • Register your webhook URL. You will make a POST request to a /webhooks.json?url= endpoint. When you make this request Twitter will issue a CRC request to your web app. When a webhook is successfully registered, the response will include a webhook id. This webhook id is needed later when making some requests to the Account Activity API. 
  • Twitter will send account webhook events to the URL you registered. Make sure your web app supports POST requests for incoming events. These events will be encoded in JSON. See HERE for example webhook JSON payloads.
  • Once your web app is ready, the next step is adding accounts to receive activities for. When adding (or deleting) accounts you will make POST requests referencing the account id. See our guide on adding subscriptions for more information.

4. Validate setup

  • To validate your app and webhook are configured correctly, favorite a Tweet posted by one of the Twitter accounts your app is subscribed to. You should receive a favorite_events via a POST request to your webhook URL for each Favorite your subscribers receive.

 

Important Notes

  • When registering your webhook URL, your app must authenticate with its consumer token and secret and its user access token and secret
  • All incoming Direct Messages will be delivered via webhooks. All Direct Messages sent via POST direct_messages/events/new (message_create) will also be delivered via webhooks. This is so your app can be aware of Direct Messages sent via a different client.
  • Note that every webhook event includes a for_user_id user ID that indicates which subscription the event was delivered for.
  • If you have two users using your app for Direct Messages in the same conversation, your webhook will receive two duplicate events (one for each user). Your app should account for this. 
  • If you have more than one app sharing the same webhook URL and the same user mapped to each app, the same event will be sent to your webhook multiple times (once per app).
  • In some cases, your webhook may receive duplicate events. Your webhook application should be tolerant of this and dedupe by event ID.
  • Do not expect Quick Reply response to directly follow a request. A user has the ability to ignore a Quick Reply request and may respond via traditional Direct Message. The user may also provide a Quick Reply response to a request they have not replied to earlier in the message thread.

 

Next steps