Webhooks

Register a webhook so your AI agent receives real-time monitor events

Push delivery for event-driven agents (Claude, OpenClaw, Hermes, or any HTTPS service): we POST a signed event to your endpoint the moment a monitored account posts (tweet.new), replies, retweets, or quotes — so your agent reacts in real time instead of polling. A terminal monitor.expired / monitor.deleted event fires once when a monitor ends, so silence is never ambiguous. Free (SIWX). Your HTTPS endpoint receives a signed POST for every event from every monitor this wallet owns (optionally filtered by eventTypes). VERIFY EVERY DELIVERY: recompute sha256=HMAC-SHA256(secret, ${X-Twitr-Timestamp}.${rawBody}) and constant-time-compare against the X-Twitr-Signature header; reject timestamps older than 5 minutes; dedupe on the envelope's delivery_id (per retry) and id (per event). Respond 2xx within 10 seconds — do slow work async. Delivery envelope: {type, id, delivery_id, monitor_id, occurred_at, received_at, source, data}. Retries back off over ~36 minutes (max 6 attempts) before marking the delivery failed; 50 consecutive failures auto-pause the webhook (a successful /test re-activates it). Max 3 webhooks per wallet.

post/api/webhooks

Request

  • Base URL: https://twitr.sh
  • URL: https://twitr.sh/api/webhooks
  • Auth: API key in header SIGN-IN-WITH-X

Request body

urlstring required

Public HTTPS endpoint your agent listens on (hostnames only — no IPs/localhost).

eventTypesstring[]

Which events to receive (default: all). Post events (tweet.) fire for any monitor; profile-change events (profile..changed) fire for account monitors only. Lifecycle events (monitor.expired, monitor.deleted) fire once when a monitor ends.

Response

Created — body carries {webhook, secret (once), note}.

Changes

No recorded changes to this operation across all 1 revision of this API.