App Webhooks

Overview

Your OAuth app can receive event notifications (e.g. a post was created or updated) at a webhook URL, delivered through FeatureOS's standard webhook pipeline — with retries and HMAC signing. This requires the webhooks:manage scope.

The model mirrors scopes: your app subscribes to the events it can handle, and each install grants a subset that's actually delivered.

1. Declare the webhook on your app

Set webhook_url and subscribed_webhook_events when you register (or update) the app. These are only accepted if webhooks:manage is in your declared_scopes.

curl -sX POST https://api.featureos.app/oauth/apps \
  -H "Authorization: Bearer <USER_JWT>" \
  -H "X-Organization: your-org" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration",
    "redirect_uris": ["https://myapp.com/callback"],
    "allowed_actor_modes": ["app"],
    "declared_scopes": ["posts:read", "webhooks:manage"],
    "webhook_url": "https://myapp.com/webhooks/featureos",
    "subscribed_webhook_events": ["post_created", "post_updated"]
  }'

2. Events are granted per install

At consent, the installing org can restrict which of your subscribed events this install delivers, via granted_webhook_events (a subset of what the app subscribed to):

curl -sX POST https://api.featureos.app/oauth/authorize/consent \
  -H "Authorization: Bearer <USER_JWT>" -H "X-Organization: target-org" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "foapp_…",
    "redirect_uri": "https://myapp.com/callback",
    "actor": "app",
    "target_organization_id": 7,
    "granted_webhook_events": ["post_updated"]
  }'

Omit granted_webhook_events to grant everything the app subscribed to. When the install completes (token exchange), a webhook is automatically provisioned in the target org subscribed only to the granted events.

Supported events

Lifecycle

• Provisioned automatically on install (token exchange), for the target org, subscribed to the granted events.
• URL changes to your app propagate to all existing installs automatically.
• Removed automatically when the install is revoked or the app is suspended.

For payload format, signing, and retry behavior, see the main Webhooks documentation — app webhooks use the same delivery system.