Skip to content

Processing Webhooks - API Reference

When a monitor detects an update (e.g., a new tweet from the target user), the API sends a request to your webhook URL. Each webhook request contains a single tweet or user profile. If the API detects multiple updates simultaneously, it dispatches an individual webhook request for each event.

The API first checks for a monitor-specific webhook_url. If not set, it uses your global webhook URL.

Currently, the API does not retry failed requests. However, this behavior may change in the future. We recommend always returning HTTP Status 200 for successfully received webhook requests.

Webhook Payload

Each request contains 3 properties:

  • event defines the type of event that triggered a webhook and will always be one of new_tweet, new_following, profile_update.
  • data contains the actual data of the event and is consistent with our tweet details or user details endpoints depending on the type of monitor.
  • meta contains details of the monitor that triggered the event.
{
    "event": "new_tweet",
    "data": {
        // ... Tweet details ...
    },
    "meta": {
        "monitor_id": "01hx1r99s0nsqq1ffdhmyyqbfr",
        "monitor_type": "user_tweets",
        "monitored_id_str": "44196397"
    }
}

Event Examples

{
  "event": "new_following",
  "data": {
    "id": 295218901,
    "id_str": "295218901",
    "name": "vitalik.eth",
    "screen_name": "VitalikButerin",
    "location": "Earth",
    "url": null,
    "description": "mi pinxe lo crino tcati",
    "protected": false,
    "verified": true,
    "followers_count": 5702740,
    "friends_count": 465,
    "listed_count": 37058,
    "favourites_count": 8856,
    "statuses_count": 20628,
    "created_at": "2011-05-08T16:03:03.000000Z",
    "profile_banner_url": "https://pbs.twimg.com/profile_banners/295218901/1638557376",
    "profile_image_url_https": "https://pbs.twimg.com/profile_images/1880759276169224192/rXpjZO0A_normal.jpg",
    "can_dm": false
  },
  "meta": {
    "monitor_id": "01jkf3zgfwt8gnpgevxf9w6h58",
    "monitor_type": "user_following",
    "monitored_id_str": "1659965172780511232"
  }
}