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 a Twitter app with an approved developer account from the developer portal. If you are creating the app on behalf of your company, it is recommended you create the app with a corporate Twitter account. To apply for a developer account, click here.

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 the "Apps" page of the developer portal. 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:

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 web 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 web 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 web app for Direct Messages in the same conversation, your webhook will receive two duplicate events (one for each user). Your web app should account for this.

If you have more than one web 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 web app).

In some cases, your webhook may receive duplicate events. Your webhook app 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.

See Account Activity API references. The Account Activity API is available for both enterprise and premium API families. One important difference is the URL pattern of the endpoint. See the respective API reference for more details.

By using Twitter’s services you agree to our Cookies Use. We use cookies for purposes including analytics, personalisation, and ads.

This page and certain other Twitter sites place and read third party cookies on your browser that are used for non-essential purposes including targeting of ads. Through these cookies, Google, LinkedIn and NewsCred collect personal data about you for their own purposes. Learn more.