Receiving Webhook Events

The request to your webhook URL is a POST request. All requests to your webhook URL are over HTTPS. Currently, only Direct Message events are available via the Account Activity API.

A user subscription created with POST account_activity/webhooks/:webhook_id/subscriptions is required to receive events for a user. Events for messages recieved AND sent to a user will be sent to the webhook. The source_app_id, recipient_id or sender_id can help determine if the message is incomming or outgoing from the user or application.

In some cases your webhook may receive duplicate events. Your webhook application should be tolerant of this and dedupe by event ID.

Callback requests contain three top level objects.

Name Description
direct_message_events An array of Direct Message Event objects.
users An object containing hydrated user objects keyed by user ID.
apps An object containing hydrated application objects keyed by app ID.

Example Request - Outgoing Message

{
  "direct_message_events": [
    {
      "type": "message_create",
      "id": "1234858585",
      "created_timestamp": "1392078023507",
      "message_create": {
        "target": {
          "recipient_id": "3805104374"
        },
        "sender_id": "1234858592",
        "source_app_id": "8829219",
        "message_data": {
          "text": "What's your favorite type of bird?",
          "entities": {
            "hashtags": [],
            "symbols": [],
            "urls": [],
            "user_mentions": [],
          },
          "quick_reply": {
            "type": "options",
            "options": [
              { "label": "Red Bird" , "metadata": "external_id_1"  },
              { "label": "Blue Bird" , "metadata": "external_id_2" },
              { "label": "Black Bird" , "metadata": "external_id_3" },
              { "label": "White Bird" , "metadata": "external_id_4" }
            ]
          },
          "attachment": {
            "type": "media",
            "media": {
             ...
            }
          }
        }
      }
    }
    ...
  ],
  "users": {
    "1234858592": {
      "id": "1234858592",
      "created_timestamp": "1415320482361",
      "name": "TwitterDev",
      "screen_name": "TwitterDev",
      "location": "Internet",
      "description": "Developer and Platform Relations @Twitter. We are developer advocates. We can't answer all your questions, but we listen to all of them!",
      "protected": false,
      "verified": true,
      "followers_count": 440643,
      "friends_count": 1534,
      "statuses_count": 2837,
      "profile_image_url": "http://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png",
      "profile_image_url_https": "https://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png"
    },
    "3805104374": {
      "id": "3805104374",
      "created_timestamp": "1449607341142",
      "name": "Furni",
      "screen_name": "furni",
      "location": "San Francisco, CA",
      "description": "Furni is Twitter's example company to showcase new developer features.",
      "protected": false,
      "verified": false,
      "followers_count": 297,
      "friends_count": 7,
      "statuses_count": 1,
      "profile_image_url": "http://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png",
      "profile_image_url_https": "https://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png"
    }
  },
  "apps": {
    "8829219": {
      "id": "8829219",
      "name": "Furni",
      "url": "https://twitter.com/furni"
    }
  }
}

Example Request - Incoming Message

If a quick reply response is included in the incoming message, the type and metadata will be present in the quick_reply_response object. The label for the chosen option is sent as the message text. The users object contains hydrated condensed user objects using user IDs in direct_message_event objects as keys.

{
  "direct_message_events": [
    {
      "type": "message_create",
      "id": "1234858589",
      "created_timestamp": "1392078023603",
      "message_create": {
        "target": {
          "recipient_id": "1234858592"
        },
        "sender_id": "3805104374",
        "source_app_id": "268278",
        "message_data": {
          "text": "Blue Bird",
          "entities": {
            "hashtags": [],
            "symbols": [],
            "urls": [],
            "user_mentions": [],
          },
          "quick_reply_response": {
            "type": "options",
            "metadata": "external_id_2"
          },
          "attachment": {
            "type": "media",
            "media": {
             ...
            }
          }
        }
      }
    }
    ...
  ],
  "users": {
    "1234858592": {
      "id": "1234858592",
      "created_timestamp": "1415320482361",
      "name": "TwitterDev",
      "screen_name": "TwitterDev",
      "location": "Internet",
      "description": "Developer and Platform Relations @Twitter. We are developer advocates. We can't answer all your questions, but we listen to all of them!",
      "protected": false,
      "verified": true,
      "followers_count": 440643,
      "friends_count": 1534,
      "statuses_count": 2837,
      "profile_image_url": "http://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png",
      "profile_image_url_https": "https://pbs.twimg.com/profile_images/530814764687949824/npQQVkq8_normal.png"
    },
    "3805104374": {
      "id": "3805104374",
      "created_timestamp": "1449607341142",
      "name": "Furni",
      "screen_name": "furni",
      "location": "San Francisco, CA",
      "description": "Furni is Twitter's example company to showcase new developer features.",
      "protected": false,
      "verified": false,
      "followers_count": 297,
      "friends_count": 7,
      "statuses_count": 1,
      "profile_image_url": "http://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png",
      "profile_image_url_https": "https://pbs.twimg.com/profile_images/653712801219805185/S4LvoO9b_normal.png"
    }
  },
  "apps": {
    "268278": {
      "id": "268278",
      "name": "Twitter Web Client",
      "url": "http://twitter.com"
    }
  }
}