Subscriptions

Overview

Webhook Subscription

The Webhook Subscription resource allows registering endpoints that will receive real-time notifications when document events occur.

Each subscription defines:

The target URL to receive notifications
The event type to subscribe to
The authentication method used when delivering notifications

Endpoints

GET - /subscription-management
GET - /subscription-management/{id}
POST - /subscription-management
PUT - /subscription-management/{id}
DELETE - /subscription-management/{id}

How it works

When a relevant event occurs on a document, the platform delivers an HTTP POST request to the registered notificationUrl. The request body contains a structured payload describing the event — see the Notifications page for details on the payload structure.

The subscriber identity is resolved automatically from the authenticated context. The subscriber is not declared explicitly, the platform extracts it from the service account present in the JWT token.

Multiple subscriptions may be registered, for example to separate notification endpoints per event type.

Authentication methods

When registering a subscription, the authentication method the platform will use when delivering notifications must be configured.

Method	Description
`OAUTH2`	The platform obtains an access token from the configured authorization server before each delivery attempt.
`BASIC_AUTH`	Credentials are included in the `Authorization` header of each notification request using HTTP Basic authentication.
`API_KEY`	A static API key is sent as a custom header on each notification request.

Endpoints

List webhook subscriptions

GET - /subscription-management

Returns all webhook subscriptions associated with the authenticated account.

The subscriber identity is resolved from the JWT token — no additional parameters are required. The response contains the full list of configured subscriptions, including their target URLs, event types, and authentication methods. Credential values (secrets, passwords, keys) are not returned.

Responses

Status	Description	Content-Type	Schema
`200`	List of subscriptions	`application/json`	`WebhookSubscriptionResponse`
`401`	Unauthorized	—	—
`500`	Internal server error	—	—

Example Request

GET /subscription-management
Authorization: Bearer $ACCESS_TOKEN

Get webhook subscription

GET - /subscription-management/{id}

Returns a single webhook subscription by its unique identifier.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Subscription identifier (UUID format).

Responses

Status	Description	Content-Type	Schema
`200`	Subscription found	`application/json`	`WebhookSubscriptionResponse`
`400`	Invalid subscription ID format	—	—
`401`	Unauthorized	—	—
`404`	Subscription not found	—	—
`500`	Internal server error	—	—

Example Request

GET /subscription-management/a3f1c2d4-1234-5678-abcd-ef0123456789
Authorization: Bearer $ACCESS_TOKEN

Create webhook subscription

POST - /subscription-management

Creates a new webhook subscription for the authenticated account.

The platform will begin delivering notifications to the configured notificationUrl for the selected event type as soon as the subscription is created. The authentication method provided determines how the platform authenticates itself when sending each notification.

Request Body

Content-Type	Schema
`application/json`	`WebhookSubscriptionRequest`

Fields

Name	Type	Required	Description
`notificationUrl`	string	Yes	HTTPS endpoint that will receive event notifications.
`eventType`	string	Yes	Event type to subscribe to. Allowed values: `DOCUMENT_STATUS_CHANGED`, `INVOICE_STATUS_CHANGED`.
`description`	string	No	Optional label for this subscription (e.g., `"Production listener"`).
`authentication`	object	Yes	Authentication configuration. See Authentication methods.

Authentication object — `OAUTH2`

Name	Type	Required	Description
`method`	string	Yes	Must be `OAUTH2`.
`clientId`	string	Yes	Client ID for the authorization server.
`clientSecret`	string	Yes	Client secret for the authorization server.
`tokenUrl`	string	Yes	Token endpoint URL used to obtain an access token.

Authentication object — `BASIC_AUTH`

Name	Type	Required	Description
`method`	string	Yes	Must be `BASIC_AUTH`.
`username`	string	Yes	Username included in the `Authorization` header.
`password`	string	Yes	Password included in the `Authorization` header.

Authentication object — `API_KEY`

Name	Type	Required	Description
`method`	string	Yes	Must be `API_KEY`.
`headerName`	string	Yes	Name of the header where the API key will be sent.
`key`	string	Yes	Static API key value sent on each notification.

Responses

Status	Description	Content-Type	Schema
`201`	Subscription created	`application/json`	`WebhookSubscriptionResponse`
`400`	Invalid request parameters	—	—
`401`	Unauthorized	—	—
`500`	Internal server error	—	—

Example Request (OAuth2)

POST /subscription-management
Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "notificationUrl": "https://your-server.com/webhook",
  "eventType": "DOCUMENT_STATUS_CHANGED",
  "description": "Production listener",
  "authentication": {
    "method": "OAUTH2",
    "clientId": "my-client-id",
    "clientSecret": "my-client-secret",
    "tokenUrl": "https://auth.your-server.com/oauth/token"
  }
}

Example Request (API Key)

POST /subscription-management
Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "notificationUrl": "https://your-server.com/webhook",
  "eventType": "INVOICE_STATUS_CHANGED",
  "description": "Invoice status listener",
  "authentication": {
    "method": "API_KEY",
    "headerName": "X-API-Key",
    "key": "my-secret-api-key"
  }
}

Update webhook subscription

PUT - /subscription-management/{id}

Updates the target URL, event type, description, or authentication configuration of an existing subscription.

All fields in the request body are replaced. To keep an existing value, include it unchanged in the request.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Subscription identifier (UUID format).

Request Body

Content-Type	Schema
`application/json`	`WebhookSubscriptionUpdateRequest`

The request body accepts the same fields as the Create webhook subscription endpoint.

Responses

Status	Description	Content-Type	Schema
`200`	Subscription updated	`application/json`	`WebhookSubscriptionResponse`
`400`	Invalid request parameters	—	—
`401`	Unauthorized	—	—
`404`	Subscription not found	—	—
`500`	Internal server error	—	—

Example Request

PUT /subscription-management/a3f1c2d4-1234-5678-abcd-ef0123456789
Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "notificationUrl": "https://your-server.com/webhook-v2",
  "eventType": "DOCUMENT_STATUS_CHANGED",
  "description": "Updated production listener",
  "authentication": {
    "method": "BASIC_AUTH",
    "username": "webhook-user",
    "password": "s3cr3t"
  }
}

Delete webhook subscription

DELETE - /subscription-management/{id}

Permanently removes a webhook subscription. Once deleted, the platform will stop delivering notifications to the associated endpoint.

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	Subscription identifier (UUID format).

Responses

Status	Description
`204`	Subscription deleted
`400`	Invalid subscription ID format
`401`	Unauthorized
`404`	Subscription not found
`500`	Internal server error

Example Request

DELETE /subscription-management/a3f1c2d4-1234-5678-abcd-ef0123456789
Authorization: Bearer $ACCESS_TOKEN

Overview

How it works

Authentication methods

Endpoints

GET - /subscription-management

Responses

Example Request

GET - /subscription-management/{id}

Path Parameters

Responses

Example Request

POST - /subscription-management

Request Body

Fields

Authentication object — OAUTH2

Authentication object — BASIC_AUTH

Authentication object — API_KEY

Responses

Example Request (OAuth2)

Example Request (API Key)

PUT - /subscription-management/{id}

Path Parameters

Request Body

Responses

Example Request

DELETE - /subscription-management/{id}

Path Parameters

Responses

Example Request

Authentication object — `OAUTH2`

Authentication object — `BASIC_AUTH`

Authentication object — `API_KEY`