Back to Blog

Push new posts to your webhook with monitors

Create a monitor once and let the API deliver matching posts to your URL.

Polling an account every minute is the most expensive way to find out that something new was posted. A monitor inverts it: you declare the account and the filter once, and the API pushes matching posts to your webhook.

Create a monitor

curl -X POST 'https://api.skilltweet.com/v1/monitors' \
  -H 'X-API-KEY: $AGENTTWEET_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "username": "openai",
    "keywords": ["api", "launch"],
    "webhook_url": "https://example.com/hooks/x",
    "interval_minutes": 5
  }'
FieldConstraints
usernameThe X handle to watch, 1–15 characters, without the @
keywordsOptional filter, up to 10 terms of 1–24 characters; empty means every post
webhook_urlWhere matching posts are delivered; optional, monitors also work without it
interval_minutesPolling cadence, 1 to 1,440 minutes, default 5

One key owns its own monitors: GET /v1/monitors lists them, DELETE /v1/monitors/:id removes one.

What your endpoint receives

New posts are delivered as a JSON POST with content-type: application/json and the user agent AgentTweet-Monitor/1.0:

{
  "event": "tweet.new",
  "monitor_id": "…",
  "username": "openai",
  "delivered_at": "2026-11-10T09:15:00.000Z",
  "tweets": [
    { "id": "…", "text": "…", "author": "…" }
  ]
}

Two details worth knowing before you write the handler:

  • The first cycle never fires the webhook. Otherwise creating a monitor would dump the account's whole recent history at you in one burst. Delivery starts from the second poll on, and only for posts that appeared in between.
  • Delivery is best effort with a 10-second budget. Return any 2xx quickly and process asynchronously; if your endpoint is slow or down, that cycle is logged as a failed delivery rather than retried forever.

The posts in tweets are the same flat JSON you would get from /v1/tweets/search, so one handler covers both paths.

Filtering without code

keywords is matched server-side, so a monitor on a noisy account with three keywords costs the same as one without, while your endpoint only wakes up for posts that matter. Keep webhook_url empty when you would rather poll on your own schedule — GET /v1/monitors and the timeline endpoints cover that case.

Where to go next