# PingWhen for agents

Pay the same Starter ($9/mo, 10 watches, every 15 min) or Plus ($19/mo, 40 watches, every 5 min) Stripe subscription as humans. No agent-only price. No x402 required.

## 1. Create a watch

`POST https://pingwhen.app/v1/watches`

```json
{
  "url": "https://example.com",
  "notify": "https://agent.example/hooks/pingwhen",
  "events": ["change", "down"],
  "plan": "starter",
  "success_url": "https://agent.example/paid",
  "cancel_url": "https://agent.example/abandoned"
}
```

`notify` may be a webhook URL (preferred), email, or US/CA phone.

The Worker validates the watch URL (SSRF rules), inserts `status=pending_payment`, opens Stripe Checkout, and returns 201 immediately. Polling does not start until paid.

```json
{
  "watch_id": "w_...",
  "status": "pending_payment",
  "manage_token": "mt_...",
  "plan": "starter",
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_...",
  "poll": "GET /v1/watches/w_...?token=mt_...",
  "cancel": "DELETE /v1/watches/w_...?token=mt_...",
  "instructions": "Open checkout_url in a browser. Then poll until status=active."
}
```

If `notify` is an email for an existing customer with spare quota, Checkout is skipped and `status=active`.

## 2. Poll

`GET https://pingwhen.app/v1/watches/:id?token=mt_...`

Status: `pending_payment` | `active` | `past_due` | `canceled` | `expired`.

Once active, the JSON includes `portal_url` (Stripe Customer Portal).

## 3. Alerts

HTTPS webhook POST:

```json
{
  "event": "change" | "down" | "up" | "active",
  "watch_id": "w_...",
  "url": "https://example.com",
  "checked_at": "2026-09-20T20:04:00Z",
  "http_status": 200,
  "excerpt": "text now includes $19/mo"
}
```

Headers: `User-Agent: PingWhenBot/1.0`, `X-PingWhen-Signature: sha256=<hmac of raw body with manage_token>`, `X-PingWhen-Event`.

Respond `410` or `{"ok":false,"unsubscribe":true}` to delete the watch.

## 4. Cancel

`DELETE https://pingwhen.app/v1/watches/:id?token=mt_...` removes that watch. Hand the user `portal_url` to cancel the Stripe subscription.

OpenAPI: https://pingwhen.app/v1/openapi.json