# Webhooks — Apparel Monster

Apparel Monster's event-push model for agents and integrators.

## Current state

**Outbound HTTP webhooks** are not self-serve on the public Storefront API as of today. We support three push-alternatives that cover the same use cases:

1. **MCP server notifications** — `notifications/resources/updated` and `notifications/progress` flow over the streamable-HTTP transport. Best for real-time agent integrations.
2. **Order-status polling** — `GET /api/v2/storefront/order_status/{order_number}` returns current payment/shipment state. Poll every 5–10 seconds during active fulfillment; every 60–120 seconds otherwise.
3. **Admin-configured webhooks** (Platform API) — Spree admins can configure outbound webhooks for order, stock, and customer events. Contact the webmaster to enable.

## Event types

| Event | Trigger | Delivery method |
|---|---|---|
| `order.created` | New order completed checkout | Admin webhook OR polling |
| `order.status_changed` | `pending` → `complete`, or shipment state transitions | Admin webhook OR polling |
| `shipment.shipped` | Shipment marked as shipped in admin | Admin webhook |
| `shipment.delivered` | Delivery confirmation | Admin webhook |
| `product.updated` | Product edited (price, description, images) | MCP `notifications/resources/updated` |
| `variant.stock_changed` | Stock crossed threshold | MCP `notifications/resources/updated` |
| `price.dropped` | Variant price reduced | MCP `notifications/resources/updated` |

## Webhook payload (when configured)

Admin webhooks POST JSON to your configured URL:

```json
{
  "event":     "order.status_changed",
  "timestamp": "2026-04-18T20:12:34Z",
  "resource": {
    "type":   "order",
    "id":     "123",
    "number": "R123456789",
    "state":  "complete",
    "previous_state": "pending"
  },
  "signature": "t=1713456789,v1=a3f2c..."
}
```

Each webhook carries an HMAC-SHA256 signature in the `signature` header (`t=<timestamp>,v1=<hmac>`) for verification. Reject any webhook whose signature doesn't match or whose timestamp is more than 5 minutes old.

## Inbound webhooks (PSP)

Payment processors push events TO Apparel Monster at:

- `/api/v2/platform/payment_gateways/:id/webhook` — generic
- `/webhooks/stripe` — Stripe
- `/webhooks/forter` — tokenizer partner

These are handled server-side; agents don't interact with them directly.

## Agent-initiated subscriptions

Agents connected via MCP can subscribe to resource change notifications:

```json
{"jsonrpc":"2.0","id":42,"method":"resources/subscribe","params":{"uri":"product://apparel-monster/denim-shirt"}}
```

The server will push `notifications/resources/updated` for that resource. Unsubscribe with `resources/unsubscribe`.

## Configuration

To enable outbound webhooks for your integration:

1. Contact the webmaster with the delivery URL, events of interest, and a preferred HMAC secret.
2. We'll provision a Spree webhook subscriber (via the Platform API's `webhook_subscribers` endpoint).
3. Test the delivery using the Spree admin's webhook test tool.

See also:

- [Authentication](authentication.md) — for the Platform API scope required to manage webhook subscribers.
- [Streaming](streaming.md) — for MCP notifications as an alternative.