Skip to main content
POST
Subscribe a URL to events (REST Hooks)

Authorizations

Authorization
string
header
required

OAuth 2.1 authorization code flow with PKCE (S256 only) and exact redirect-URI matching. Clients register by Dynamic Client Registration (/api/oauth/register) or a Client ID Metadata Document. Discovery: /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp. Access tokens last one hour and refresh tokens rotate. Tokens carry the audience https://api.ai2fin.com/mcp and are accepted on /mcp and /api/integrations/v1 only. A request with no scope gets read:transactions write:transactions read:bills write:bills; write:expenses and webhooks:manage must be asked for explicitly.

Scopes

webhooks:manage

Integration API: list, create and delete webhook subscriptions (Auto+ plan also required). Does not unlock MCP write tools.

Body

application/json
url
string<uri>
required

https:// on port 443, a DNS name (no IP literal or local/internal host), at most 2048 characters. Every address the name resolves to must be public.

events
enum<string>[]
required
Minimum array length: 1
Available options:
transaction.categorized,
expense.created,
receipt.processed

Must be true: show the consent text (from the list endpoint) to the person first.

fieldFilter
enum<string>[]

Extra fields to include beyond the base fields.

Available options:
description,
reference,
notes
description
string
Maximum string length: 200

Response

Subscription created

success
boolean
subscription
object
secret
string

The signing secret (whsec_ + 64 hex). Returned only here.