---
title: "Processing Webhooks - API Reference"
description: "How SocialData delivers monitor events to your webhook URL, the payload shape for each event type, and how to recover events your endpoint missed"
source: "https://docs.socialdata.tools/monitoring/processing-webhooks/"
---
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](https://docs.socialdata.tools/monitoring/set-global-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](https://docs.socialdata.tools/monitoring/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](https://docs.socialdata.tools/monitoring/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](https://docs.socialdata.tools/reference/get-tweet/) or [user details](https://docs.socialdata.tools/reference/get-user-profile/) 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.
```json
{
"event": "new_tweet",
"data": {
// ... Tweet details ...
},
"meta": {
"monitor_id": "01hx1r99s0nsqq1ffdhmyyqbfr",
"monitor_type": "user_tweets",
"monitored_id_str": "44196397",
"monitored_username": "elonmusk"
}
}
```
## Event Examples
#### New Following
```json
{
"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"
}
}
```
#### New Tweet
```json
{
"event": "new_tweet",
"data": {
"tweet_created_at": "2025-02-12T02:43:10.000000Z",
"id": 1889505498761703504,
"id_str": "1889505498761703504",
"conversation_id_str": "1889505498761703504",
"text": null,
"full_text": "Assange is right!",
"source": "Twitter for iPhone<\/a>",
"truncated": false,
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
"user": {
"id": 44196397,
"id_str": "44196397",
"name": "Elon Musk",
"screen_name": "elonmusk",
"location": "",
"url": null,
"description": "",
"protected": false,
"verified": true,
"followers_count": 217258406,
"friends_count": 1013,
"listed_count": 159662,
"favourites_count": 122139,
"statuses_count": 70054,
"created_at": "2009-06-02T20:12:29.000000Z",
"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/44196397\/1726163678",
"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/1874558173962481664\/8HSTqIlD_normal.jpg",
"can_dm": false
},
"quoted_status_id": null,
"quoted_status_id_str": "1889494636323885155",
"is_quote_status": true,
"quoted_status": {
"tweet_created_at": "2025-02-12T02:00:01.000000Z",
"id": 1889494636323885155,
"id_str": "1889494636323885155",
"conversation_id_str": "1889494636323885155",
"text": null,
"full_text": "\ud83d\udea8ASSANGE ON USAID: \u2018CIVIL SOCIETY IS A FABLE\u2019\n\nAssange exposed how NGOs have been co-opted into political weapons, arguing that civil society is no longer independent but a \u201cbuyer\u2019s market\u201d for influence:\n\n\u201cThe last forty years have seen a huge proliferation of think tanks and political NGOs whose purpose, beneath all the verbiage, is to execute political agendas by proxy.\u201d\n\nHe singled out USAID, Freedom House, and \u2018civil society\u2019 events as vehicles for Western political interests masquerading as grassroots activism.\n\nSource: @WikiLeaks",
"source": "Twitter Web Client<\/a>",
"truncated": false,
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
"user": {
"id": 1319287761048723458,
"id_str": "1319287761048723458",
"name": "Mario Nawfal",
"screen_name": "MarioNawfal",
"location": "",
"url": "https:\/\/roundtable.live",
"description": "Largest Show on X | Founder @ibcgroupio",
"protected": false,
"verified": true,
"followers_count": 2030538,
"friends_count": 44251,
"listed_count": 8614,
"favourites_count": 144210,
"statuses_count": 109900,
"created_at": "2020-10-22T14:42:25.000000Z",
"profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/1319287761048723458\/1736691634",
"profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/1670905743619268609\/pYItlWat_normal.jpg",
"can_dm": true
},
"quoted_status_id": null,
"quoted_status_id_str": null,
"is_quote_status": false,
"quoted_status": null,
"retweeted_status": null,
"quote_count": 16,
"reply_count": 51,
"retweet_count": 350,
"favorite_count": 871,
"views_count": 26067,
"bookmark_count": 54,
"lang": "en",
"entities": {
"user_mentions": [
{
"id_str": "16589206",
"name": "WikiLeaks",
"screen_name": "WikiLeaks",
"indices": [
532,
542
]
}
],
"urls": [],
"hashtags": [],
"symbols": []
},
"is_pinned": false
},
"retweeted_status": null,
"quote_count": 0,
"reply_count": 7,
"retweet_count": 0,
"favorite_count": 1,
"views_count": null,
"bookmark_count": 2,
"lang": "en",
"entities": {
"user_mentions": [],
"urls": [],
"hashtags": [],
"symbols": []
},
"is_pinned": false
},
"meta": {
"monitor_id": "01jkt060zcz108b78fke6hm1g4",
"monitor_type": "user_tweets",
"monitored_id_str": "44196397",
"monitored_username": "elonmusk"
}
}
```
#### Profile Update
```json
{
"event": "profile_update",
"data": {
"id": 44196397,
"id_str": "44196397",
"name": "Kekius Maximus",
"screen_name": "elonmusk",
"location": "",
"url": null,
"description": "",
"protected": false,
"verified": true,
"followers_count": 217258406,
"friends_count": 1013,
"listed_count": 159662,
"favourites_count": 122139,
"statuses_count": 70054,
"created_at": "2009-06-02T20:12:29.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/44196397/1726163678",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1874558173962481664/8HSTqIlD_normal.jpg",
"can_dm": false,
"changes": {
"name": {
"old": "Elon Musk",
"new": "Kekius Maximus"
}
},
"meta": {
"monitor_id": "01jkt060zcz108b78fke6hm1g4",
"monitor_type": "user_profile",
"monitored_id_str": "44196397",
"monitored_username": "elonmusk"
}
}
```