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.

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

Example Request - Outgoing Message

Callback requests contain an array of events called direct_message_events.

{
  "direct_message_events": [
    {
      "type": "message_create",
      "id": "1234858585",
      "created_timestamp": "1392078023507",
      "message_create": {
        "target": {
          "recipient_id": "2244994945"
        },
        "sender_id": "3805104374",
        "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": {
             ...
            }
          }
        }
      }
    }
    ...
  ]
}

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": "1234858592",
      "created_timestamp": "1392078023603",
      "message_create": {
        "target": {
          "recipient_id": "1234858592"
        },
        "sender_id": "3805104374",
        "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"
    }
  }
}