Inbound Webhooks API

STACK receives a provider webhook, verifies its signature, deduplicates the event, scans selected content, records the result, and forwards only when the configured policy allows it.

Create an endpoint

POST /v1/operator/inbound-webhooks

curl -X POST https://api.getstack.run/v1/operator/inbound-webhooks \
  -H "Authorization: Bearer $STACK_TOKEN" -H "Content-Type: application/json" \
  -d '{"provider":"generic","agent_id":"agt_123","forward_url":"https://worker.example/webhook"}'

Supported providers are agentmail and generic. The response returns the hosted URL and an HMAC secret once. Store the secret in the provider. Do not put it in a URL, log, or client bundle. Omit forward_url for scan-and-record only.

Manage endpoints

• GET /v1/operator/inbound-webhooks - list active and revoked endpoints.
• GET /v1/operator/inbound-webhooks/:id - get one endpoint and counters.
• DELETE /v1/operator/inbound-webhooks/:id - revoke it. Repeated revocation is safe.
• POST /v1/inbound/:provider/:slug - public provider receiver. It authenticates the provider signature, not a STACK API key.

Forwarding safety

• STACK rejects private, loopback, link-local, and internal forward URLs when the endpoint is created and again before each forward.
• A detector failure or KMS decryption failure stops processing. STACK does not forward unverified content.
• STACK checks revocation again after scanning. A mid-flight revoke returns 410 and does not forward.
• Forwarded JSON includes an x-stack-signature HMAC plus the scan verdict, endpoint ID, and provider headers.

Partner grants

A partner grant can create an endpoint only for a provider in its provider allowlist and an agent created by that grant. List, get, and revoke stay restricted to resources created by the same grant.