Getting started with webhooks

1. Set up your Twitter app

  • Create an app at 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.
  • Generate access tokens for the app owner at the bottom of the “Keys and Access Tokens” tab. On this same tab take note of your Consumer Key, Consumer Secret, Access Token and Access Token secret. You will need these to use the API.
  • If you are unfamiliar with Twitter Sign-in and how user contexts work with the Twitter API review Obtaining Access Tokens.

2. Webhook setup

  • Review Securing Webhooks documention taking special note of the Challenge Response Check (CRC) requirements.
  • Create a web app with an endpoint to use as your webhook to receive events (e.g.
  • Make sure your webhook supports POST requests for incoming events and GET requests for the CRC.
  • Register your webhook URL with your app using POST account_activity/webhooks.
  • Use the returned webhook_id to add user subscriptions with POST account_activity/webhooks/:webhook_id/subscriptions.

3. Validate setup

  • To validate your app and webhook are configured correctly, send a DM to one of the @usernames your app is subscribed to. You should recieve a DM event via a POST request to your webhook for each DM received.

Important Notes

  • 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.
  • 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 may be aware of Direct Messages sent via a different client.
  • If you have two users using your app for Direct Messages in the same conversation, your webhook will recieve 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.