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 a downstream HMAC secret once. Generic endpoints also return a separate incoming_signing_secret once. Configure the sender with the incoming key and the receiver with the downstream key. AgentMail setup is described below. Omit forward_url for scan-and-record only.

Signing setup after MCP creation

MCP creation returns metadata and setup_required: true, never signing secrets. An owner or admin completes setup through the authenticated REST API or SDK, outside the assistant conversation. There is no MCP signing setup tool or dashboard form. For a generic endpoint, choose a random incoming secret of 32 to 256 UTF-8 bytes and send it as signing_secret to PUT /v1/operator/inbound-webhooks/:id/provider-signing-secret. STACK generates a new downstream secret, returns it once, and stores both values under separate encryption contexts. Configure the provider with the incoming secret and your receiver with the returned webhook_secret. You can instead supply a distinct downstream_signing_secret in the request.

signing_configured reports whether STACK has an inbound verification key. Generic endpoints have a generated key at creation, so this field is true even when MCP has withheld that key and human setup is still required. For partner-owned tenants, use PUT /v1/partner/tenants/:tenant_id/inbound-webhooks/:wh_id/provider-signing-secret with the partner owner/admin credentials and the same request body.

AgentMail signing setup

Create the STACK endpoint with provider: agentmail, then register its hosted URL in AgentMail. AgentMail generates a signing secret beginning with whsec_. An account owner or admin sends that secret as signing_secret in a JSON body to PUT /v1/operator/inbound-webhooks/:id/provider-signing-secret. STACK encrypts it and never returns it. The endpoint reports signing_configured: false and refuses deliveries until setup is complete. The same request rotates the signing secret. For MCP-created endpoints with forwarding, also supply a random downstream_signing_secret of 32 to 256 UTF-8 bytes and configure your receiver with it. The incoming and downstream values must differ. STACK updates both encrypted keys together.

AgentMail requests must carry valid Svix signatures and a timestamp within five minutes. STACK scans the delivered payload, including nested message content. Content AgentMail omits from a large message is not included in that scan. Keep the separate downstream HMAC secret in your downstream receiver to verify forwarded deliveries.

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.
• Failed scans and downstream failures remain retryable. A concurrent attempt returns 503; a downstream failure returns 502.
• Retries carry the same idempotency-key and x-stack-event-id. The downstream receiver must deduplicate that key because delivery can repeat after a lost acknowledgement.

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.