webhook-subscriptions

# Webhook Subscriptions

Create webhook subscriptions so external services can trigger agent runs by POSTing events to Moltis.

Webhooks are available as soon as the Moltis gateway is running — no extra setup needed.

## Ingress Endpoint

Each webhook gets a unique URL:

```
POST https://<moltis-host>/api/webhooks/ingest/{public_id}
```

The `public_id` is a high-entropy identifier like `wh_a1b2c3d4...` assigned at creation.

## Managing Webhooks

Webhooks are managed via RPC or the web UI. The RPC namespace is `webhooks.*`.

### Create a webhook

```json
// RPC: webhooks.create
{
  "name": "github-issues",
  "description": "Triage new GitHub issues",
  "source_profile": "github",
  "auth_mode": "github_hmac_sha256",
  "auth_config": { "secret": "your-github-webhook-secret" },
  "event_filter": { "allow": ["issues.opened", "issues.reopened"] },
  "session_mode": "per_entity",
  "system_prompt_suffix": "Triage this issue: assign a priority label and suggest next steps."
}
```

Returns the webhook with its `public_id` (the URL slug) and all configuration.

### List webhooks

```json
// RPC: webhooks.list
```

### Get webhook details

```json
// RPC: webhooks.get
{ "id": 123 }
```

### Update a webhook

```json
// RPC: webhooks.update
{
  "id": 123,
  "patch": {
    "enabled": false,
    "event_filter": { "allow": ["issues.opened"], "deny": ["issues.closed"] }
  }
}
```

### Delete a webhook

```json
// RPC: webhooks.delete
{ "id": 123 }
```

### View deliveries

```json
// RPC: webhooks.deliveries
{ "webhookId": 123, "limit": 50, "offset": 0 }

// RPC: webhooks.delivery_get
{ "id": 456 }

// RPC: webhooks.delivery_payload
{ "id": 456 }
```

## Source Profiles

Each webhook has a `source_profile` that determines how events are parsed and authenticated. Use the profile that matches the sending service for best results.

| Profile | Auth Mode | Event Parsing | Dedup Header |
|---------|-----------|---------------|-------------|
| `github` | `github_hmac_sha256` | `x-github-event` + action | `x-github-delivery` |
| `gitlab` | `gitlab_token` | Event from headers | GitLab delivery ID |
| `stripe` | `stripe_webhook_signature` | Event type from JSON body | Stripe event ID |
| `linear` | `linear_webhook_signature` | Event from headers | Linear delivery ID |
| `pagerduty` | `pagerduty_v2_signature` | Event from headers | PagerDuty dedup key |
| `sentry` | `sentry_webhook_signature` | Event from headers | Sentry event ID |
| `generic` | `none` (or any) | `x-event-type` header | `x-delivery-id` / `idempotency-key` |

List available profiles via RPC:

```json
// RPC: webhooks.profiles
```

## Authentication Modes

| Mode | Config Keys | What It Verifies |
|------|-----------|-----------------|
| `none` | — | Nothing (open endpoint) |
| `static_header` | `header`, `value` | Exact match on a custom header |
| `bearer` | `token` | `Authorization: Bearer <token>` |
| `github_hmac_sha256` | `secret` | HMAC-SHA256 of body vs `x-hub-signature-256` |
| `gitlab_token` | `token` | Exact match of `x-gitlab-token` |
| `stripe_webhook_signature` | `secret` | Stripe `t=TIMESTAMP,v1=SIG` format with 5min tolerance |
| `linear_webhook_signature` | `secret` | HMAC-SHA256 vs `linear-signature` |
| `pagerduty_v2_signature` | `secret` | HMAC-SHA256 vs `x-pagerduty-signature` |
| `sentry_webhook_signature` | `secret` | HMAC-SHA256 vs `sentry-hook-signature` |

All verifications use constant-time comparison to prevent timing attacks.

## Session Modes

Control how webhook deliveries are grouped into agent sessions:

| Mode | Behavior | Use When |
|------|----------|----------|
| `per_delivery` | Fresh session for each POST | Independent events (alerts, deploys) |
| `per_entity` | Same session for same entity | Related events (all activity on PR #123) |
| `named_session` | Fixed session from `named_session_key` | All events share one conversation |

`per_entity` is powerful for GitHub: all events for the same PR or issue land in the same session, so the agent has full context of the conversation.

## Event Filtering

Filter which event types trigger agent runs:

```json
{
  "event_filter": {
    "allow": ["issues.opened", "pull_request.opened"],
    "deny": ["issues.closed"]
  }
}
```

- If `allow` is non-empty, only listed events pass.
- `deny` always wins over `allow`.
- Filtered events return `200 OK` with `status: filtered` (the sender sees success).

## Tool Policy

Restrict which tools the agent may use for webhook-triggered runs:

```json
{
  "tool_policy": {
    "allow": ["exec", "web_fetch"],
    "deny": ["delete_file"]
  }
}
```

## IP Allowlist

Restrict which IPs can send webhooks:

```json
{
  "allowed_cidrs": ["192.30.252.0/22", "185.199.108.0/22"]
}
```

For GitHub, use their published webhook IP ranges. CIDR check runs before auth verification.

## Common Patterns

### GitHub: triage new issues

```json
{
  "name": "github-issues",
  "source_profile": "github",
  "auth_mode": "github_hmac_sha256",
  "auth_config": { "secret": "whsec_..." },
  "event_filter": { "allow": ["issues.opened"] },
  "session_mode": "per_entity",
  "system_prompt_suffix": "Triage this issue: assign priority, suggest labels, draft a response."
}
```

Then in GitHub repo → Settings → Webhooks → Add webhook:
- **Payload URL:** `https://<moltis-host>/api/webhooks/ingest/<public_id>`
- **Content type:** `application/json`
- **Secret:** same as `auth_config.secret`
- **Events:** Select "Issues"

### GitHub: PR review assistant

```json
{
  "name": "github-prs",
  "source_profile": "github",
  "auth_mode": "github_hmac_sha256",
  "auth_config": { "secret": "whsec_..." },
  "event_filter": { "allow": ["pull_request.opened", "pull_request.synchronize"] },
  "session_mode": "per_entity",
  "system_prompt_suffix": "Review this PR for code quality, potential bugs, and style issues."
}
```

### Stripe: payment monitoring

```json
{
  "name": "stripe-payments",
  "source_profile": "stripe",
  "auth_mode": "stripe_webhook_signature",
  "auth_config