Skip to content
SocialData SocialData

Processing Webhooks - API Reference

When a monitor detects an update (e.g., a new tweet from the target user), the API makes a POST 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 (set using one of our “Create monitor” endpoints). If a monitor-specific webhook_url is not defined, it uses your default webhook URL.

Delivery guarantees

Failed requests are not retried. If your endpoint is down, times out, or returns an error, that event is not delivered again. Return HTTP status 200 as soon as you have accepted the payload, and do the processing afterwards — a slow handler is indistinguishable from a broken one.

Every event is recorded regardless of the outcome. Use Monitor event history to list what a monitor sent and to re-read any payload, which is how you backfill events your endpoint missed while it was down.

Events are deduplicated. The same detected event is never sent twice by the same monitor.

Ordering is not guaranteed. Two tweets detected at the same moment may arrive in either order. If order matters to you, sort on tweet_created_at rather than on arrival.

Delivery is billed at detection. An event your endpoint rejects is still billed, because the work of detecting it already happened.

Every request is signed. Your webhook URL is a public endpoint that anyone can POST to. Each delivery carries X-Timestamp, X-Event-Id and X-Signature headers so you can confirm it came from us — see Verifying webhooks.

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. User monitors report monitored_id_str and monitored_username; search monitors report monitored_query instead.
{
    "event": "new_tweet",
    "data": {
        // ... Tweet details ...
    },
    "meta": {
        "monitor_id": "01hx1r99s0nsqq1ffdhmyyqbfr",
        "monitor_type": "user_tweets",
        "monitored_id_str": "44196397",
        "monitored_username": "elonmusk"
    }
}

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": "01jkt060zcz108b78fke6hm1g4",
    "monitor_type": "user_following",
    "monitored_id_str": "44196397",
    "monitored_username": "elonmusk"
  }
}