--- title: "Create an account webhook endpoint" method: POST path: "/accounts/{account}/webhooks" tags: ["Account"] --- # Create an account webhook endpoint `POST /accounts/{account}/webhooks` ## Request - Base URL: `https://api.factuarea.com/v1` - URL: `https://api.factuarea.com/v1/accounts/{account}/webhooks` - Auth: one of: - HTTP bearer - API key in header `X-API-Key` Create an account webhook endpoint for HTTPS event callbacks; returns 201 and the signing `secret` once. - `account_relationship` is `own`, `managed` or `all` (default). - Needs a live key from an owner or admin (test key: 403 `insufficient_scope`). - 402 `addon_required` if the plan allows none; 422 `account_webhook_endpoint_limit_reached`. ## Path parameters - `account` string, uuid, required ## Headers - `Idempotency-Key` string - `Factuarea-Version` string, date ## Request body - CreateAccountWebhookV1Request: Create a webhook endpoint of your ACCOUNT. Required: `url` (HTTPS, up to 2048 characters) and `enabled_events` (at least one type: the company events of the public catalog and the `account.*` events of `AccountEventType`; an unknown, reserved or not released type returns 422 and nothing is created). Optional: `account_relationship` (`own`, `managed` or `all`, the default), `description` (up to 255 characters) and `api_version` (`YYYY-MM-DD`; the latest supported version when omitted). The environment is never a field: the endpoint is born in the environment of the credential and never changes it. - `url` string, required: HTTPS URL that receives the signed events (up to 2048 characters). - `enabled_events` string[], required: Event types to subscribe to, at least one: the company events of the public catalog and the `account.*` events (`AccountEventType`). Duplicates are collapsed. - `account_relationship` 'own' | 'managed' | 'all' | 'null', nullable: Whose tax IDs the endpoint hears about: `own` (the tax IDs of your account), `managed` (the accounts your account manages) or `all`. Defaults to `all`. - `description` string, nullable: Free text for the endpoint (up to 255 characters). - `api_version` string, nullable: Payload version (`YYYY-MM-DD`) to pin the endpoint to. Defaults to the latest supported version; an unsupported one returns 422 with its own subcode. ## Response `201` Account webhook endpoint created. The `Location` header contains the canonical URL of the new endpoint; the body carries its signing secret once. - object - `data` AccountWebhookWithSecret, required: An `AccountWebhook` returned once at creation or after secret rotation: the same fields PLUS the plaintext signing secret. - `id` string, uuid, required: Opaque identifier (UUID v7) of the account webhook endpoint. It is the `{webhook}` of the endpoint routes. - `object` 'account_webhook', required: Always `account_webhook`. - `environment` 'live' | 'test', required: Environment of the endpoint: always the one of the credential that created it, and it never changes. A `live` credential never sees a `test` endpoint and the other way round. A `test` endpoint never reaches the network: its deliveries are recorded with their envelope and stay `pending`. - `url` string, uri, required: HTTPS callback URL that receives the signed events. - `enabled_events` string[], required: Event types this endpoint subscribes to: the company events of the public catalog (`GET /v1/event-catalog`) and the account-level events of `AccountEventType`. Duplicates are collapsed. - `account_relationship` 'own' | 'managed' | 'all', required: Whose tax IDs the endpoint hears about: `own` (the tax IDs of your account), `managed` (the accounts your account manages) or `all` (the default). - `status` 'active' | 'disabled', required: `active` while the endpoint receives events; `disabled` once it stopped receiving them (the reason is in `disabled_reason`). - `disabled_reason` 'creator_lost_capability' | 'null', nullable, required: Why the endpoint was disabled, or `null` while it is active. `creator_lost_capability`: the person or key that created it stopped being an owner or admin of the account, or no longer reaches every tax ID of the account. - `api_version` string, nullable, required: Payload version (date-based, `YYYY-MM-DD`) pinned for this endpoint. A new endpoint is pinned to the latest version when created; `null` makes it follow the version in force on every emission. - `description` string, nullable, required: Free text you give the endpoint, or `null`. - `created_at` string, date-time, required: When the endpoint was created (ISO 8601). - `updated_at` string, date-time, required: When the endpoint was last changed (ISO 8601). - `secret` string, nullable, required: Signing secret, returned only at creation or after rotation. `null` only in an idempotent replay of that creation or rotation, because the secret is never stored. ## Other responses - `400`: `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version. - `401`: Missing or invalid API key. - `402`: The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version. - `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). - `404`: The requested resource does not exist or belongs to another company. `account_not_found`: the account in the path does not exist or is not the account of the API key. - `422`: Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any. - `429`: Rate limit exceeded. Retry after the duration in `Retry-After`. - `500`: Unexpected server error. --- [API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)