---
title: "Register a webhook so your AI agent receives real-time monitor events"
method: POST
path: "/api/webhooks"
tags: ["Webhooks"]
---

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

`POST /api/webhooks`

## Request

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

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.

## Request body

- object
  - `url` string, required: Public HTTPS endpoint your agent listens on (hostnames only — no IPs/localhost).
  - `eventTypes` string[]: 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 `201`

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

## Other responses

- `400`: Invalid url or eventTypes.
- `402`: Identity Required — sign SIWX and retry.
- `409`: Webhook limit reached (3 per wallet).
- `429`: Too many configuration changes — Retry-After set.

---

[API](https://skmtc.dev/twitr/apis/twitr-sh.md) · [All operations](https://skmtc.dev/twitr/apis/twitr-sh/llms.txt) · [OpenAPI document](https://skmtc.dev/twitr/apis/twitr-sh/revisions/f6390fcee344?raw)