twitr-sh Webhooks API

openapi: 3.2.0
info:
  title: twitr.sh Webhooks API
  version: 1.0.0
  contact:
    email: support@twitr.sh
  description: 'Pay-per-call X/Twitter data API for AI agents: single-object reads, tweet/user search, timelines, lists, communities, bulk extractions (23 tools, async with downloadable datasets), real-time account/keyword monitors (prepaid hours; events via free polling or signed webhooks), giveaway draws, trend radar, and an AI tweet composer. No signup — the wallet is the account; an optional API key (Authorization: Bearer) spends a prepaid card balance instead. Payment via x402 v2 (USDC on Base/Solana) and MPP (USDC on Tempo). Per-result reads use x402 upto on Base only: the 402 quotes a maximum, empty results cost $0, and non-empty calls have a $0.0024 minimum. Volume tools bill per returned item against a mandatory resultsLimit; extractions and monitors settle before dispatch.'
  x-guidance: 'All tools are POST /api/tools/{tool} and return 402 with payment options on first call (Base upto only for per-result reads; fixed operations can offer exact x402 and MPP); pay and retry to receive data. Volume tools (x_search, x_timeline, x_lists, x_communities non-info kinds, followers-you-know) REQUIRE resultsLimit (integer 1–10000) — you are billed per returned item and the cap is enforced upstream. x_extract is async: it returns {snapshot_id, status_url}; poll GET /api/snapshots/{id} (free, SIWX) until status=ready for a download_url. x_monitor is PREPAID by the hour: it stops at expires_at unless extended — extend early, never expect refunds on deletion; events flow to GET /api/monitors/{id}/events (free, SIWX) or your registered webhook (/api/webhooks, signed with X-Twitr-Signature). draws, x_extract and x_monitor require an Idempotency-Key header. radar + compose are flat floor-priced. GET /api/snapshots and GET /api/monitors (SIWX) list the wallet''s history for free. Errors are RFC 9457 Problem bodies (components.schemas.Problem) with machine-actionable `retryable` and `hint` fields — retryable:true means retry the SAME request unchanged after a backoff; x402 reads settle after success; prepaid operations can fail after payment. Alternative to per-call payment: send `Authorization: Bearer tw_live_…` (an API key created at /dashboard) and each call is charged to that account''s prepaid USD balance at the same prices — per-result reads charge only returned records; the free SIWX endpoints accept the same key.'
servers:
- url: https://twitr.sh
tags:
- name: Webhooks
paths:
  /api/webhooks:
    get:
      operationId: list_my_webhooks
      summary: List this wallet's webhooks
      tags:
      - Webhooks
      security:
      - siwx: []
      responses:
        '200':
          description: Webhooks (signing secrets are never included).
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          pattern: ^wh_[a-z0-9]+$
                        url:
                          type: string
                        event_types:
                          type: array
                          items:
                            type: string
                          description: Empty = all types.
                        status:
                          type: string
                          enum:
                          - active
                          - paused
                        consecutive_failures:
                          type: integer
                        created_at:
                          type: integer
                        deliveries_url:
                          type: string
                      required:
                      - id
                      - url
                      - status
        '402':
          description: Identity Required — sign SIWX and retry.
    post:
      operationId: register_webhook
      summary: Register a webhook so your AI agent receives real-time monitor events
      description: '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.'
      tags:
      - Webhooks
      x-guidance: The 201 response contains the signing secret EXACTLY ONCE — store it immediately. Use /rotate if it is ever lost or leaked.
      security:
      - siwx: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: Public HTTPS endpoint your agent listens on (hostnames only — no IPs/localhost).
                eventTypes:
                  type: array
                  items:
                    type: string
                    enum:
                    - tweet.new
                    - tweet.reply
                    - tweet.retweet
                    - tweet.quote
                    - tweet.media
                    - tweet.link
                    - tweet.poll
                    - tweet.mention
                    - tweet.hashtag
                    - tweet.longform
                    - profile.avatar.changed
                    - profile.banner.changed
                    - profile.name.changed
                    - profile.username.changed
                    - profile.bio.changed
                    - profile.location.changed
                    - profile.url.changed
                    - profile.verified.changed
                    - profile.protected.changed
                    - profile.pinned_tweet.changed
                    - profile.unavailable.changed
                    - monitor.expired
                    - monitor.deleted
                  description: '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.'
              required:
              - url
            example:
              url: https://agent.example.com/hooks/x-events
              eventTypes:
              - tweet.new
      responses:
        '201':
          description: Created — body carries {webhook, secret (once), note}.
        '400':
          description: Invalid url or eventTypes.
        '402':
          description: Identity Required — sign SIWX and retry.
        '409':
          description: Webhook limit reached (3 per wallet).
        '429':
          description: Too many configuration changes — Retry-After set.
  /api/webhooks/{id}:
    get:
      operationId: get_webhook
      summary: Webhook detail (never the secret)
      tags:
      - Webhooks
      security:
      - siwx: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^wh_[a-z0-9]+$
      responses:
        '200':
          description: Webhook detail.
        '402':
          description: Identity Required.
        '403':
          description: Not your webhook.
        '404':
          description: Unknown webhook.
    delete:
      operationId: delete_webhook
      summary: Delete a webhook and its delivery log
      tags:
      - Webhooks
      security:
      - siwx: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^wh_[a-z0-9]+$
      responses:
        '200':
          description: Deleted.
        '402':
          description: Identity Required.
        '403':
          description: Not your webhook.
        '404':
          description: Unknown webhook.
  /api/webhooks/{id}/rotate:
    post:
      operationId: rotate_webhook_secret
      summary: Rotate the signing secret (shown once)
      description: The old secret stops verifying immediately.
      tags:
      - Webhooks
      security:
      - siwx: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^wh_[a-z0-9]+$
      responses:
        '200':
          description: '{id, secret, rotated_at} — store the secret now.'
        '402':
          description: Identity Required.
        '403':
          description: Not your webhook.
  /api/webhooks/{id}/test:
    post:
      operationId: test_webhook
      summary: Send a signed webhook.test delivery
      description: Verifies reachability + your signature handling. A 2xx from your receiver re-activates a paused webhook.
      tags:
      - Webhooks
      security:
      - siwx: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^wh_[a-z0-9]+$
      responses:
        '200':
          description: '{success, status_code, webhook}.'
        '402':
          description: Identity Required.
        '403':
          description: Not your webhook.
  /api/webhooks/{id}/deliveries:
    get:
      operationId: list_webhook_deliveries
      summary: Recent delivery log (7 days)
      tags:
      - Webhooks
      security:
      - siwx: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^wh_[a-z0-9]+$
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: after
        in: query
        schema:
          type: string
        description: Cursor — last delivery id seen.
      responses:
        '200':
          description: 'Deliveries, newest first: {id, event_id, event_type, status (pending|delivered|retrying|failed|test), attempts, last_status_code, last_error, created_at, delivered_at}.'
        '402':
          description: Identity Required.
        '403':
          description: Not your webhook.
components:
  securitySchemes:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X
      description: Sign-In-With-X (CAIP-122). Base64-encoded CAIP-122 payload signed by the caller's wallet. Server recovers the signer address cryptographically; any client-supplied wallet parameter is ignored.
    bearerKey:
      type: http
      scheme: bearer
      description: Optional API key (tw_live_…) created in the dashboard. Paid tools charge the key owner's prepaid USD balance instead of an on-chain payment; free endpoints accept it in place of SIWX.
    publicRead:
      type: apiKey
      in: query
      name: _public
      description: No-op placeholder. This endpoint requires no authentication; the scheme exists so validators that want a named security reference on public operations have one to point at.
x-ux-hints: Confirm with the user before any call that quotes above $0.10 or requests resultsLimit >= 500. Never spin a background poll loop — when the user asks progress on an extraction, call /api/snapshots/{id} (free, SIWX). Send Idempotency-Key with paid calls so a dropped response is replayed from cache (10 min) instead of re-running. Wallet history is free — use it when the user asks 'what have I extracted?'.
x-service-info:
  categories:
  - data
  - social
  - search
  - developer-tools
  docs:
    homepage: https://twitr.sh
    apiReference: https://twitr.sh/openapi.json
    llms: https://twitr.sh/llms.txt
x-discovery:
  ownershipProofs: []