Webhook API

Operations related to Web hooks

Get Webhook Configuration

get

https://api-qa.qvalia.comhttps://api.qvalia.com

/account/{accountRegNo}/webhook/configure

An API to fetch (GET) the webhook subscription for your Partner account.

Partner or Partners Account

Partners can configure their own web hooks through /partner/{partnerRegNo}/webhook/... URI, or their child accounts using /partner/{partnerRegNo}/account/{accountRegNo}/webhook/.... The latter is useful if you want to scope the subscription to a single account.

parameter accountRegNo is only required for child accounts, and should be omitted for the Partner account itself.

Authorizations

api_keyjwt

AuthorizationstringRequired

Path parameters

accountRegNostringRequired

Account registration number issued by Qvalia

Responses

200

OK

application/json

idstring · uuidOptionalExample: a1b2c3d4-5678-90ab-cdef-1234567890ab

urlstringOptionalExample: https://example.com/webhooks/qvalia

typesstring[]OptionalExample: ["new_document","document_delivery"]

accountRegNostringOptionalExample: SE1234567890

enabledbooleanOptionalExample: true

authTypestring · enum · nullableOptionalExample: api_keyPossible values:

createdAtstring · date-timeOptionalExample: 2024-01-01T12:00:00.000Z

updatedAtstring · date-timeOptionalExample: 2024-01-02T12:00:00.000Z

204

No Content

text/plain

401

Unauthorized

text/plain

500

Internal Server Error

application/json

get/account/{accountRegNo}/webhook/configure

HTTPcURLJavaScriptPython

GET /account/{accountRegNo}/webhook/configure HTTP/1.1
Host: api-qa.qvalia.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "url": "https://example.com/webhooks/qvalia",
  "types": [
    "new_document",
    "document_delivery"
  ],
  "accountRegNo": "SE1234567890",
  "enabled": true,
  "authType": "api_key",
  "createdAt": "2024-01-01T12:00:00.000Z",
  "updatedAt": "2024-01-02T12:00:00.000Z"
}

Configure Webhook

put

https://api-qa.qvalia.comhttps://api.qvalia.com

/account/{accountRegNo}/webhook/configure

An API to create or update (PUT) the webhook subscription for your account.

An account has a single webhook subscription. The first PUT creates it and returns a generated webhook id (a UUID v4); subsequent PUT requests update the same subscription (its url and/or types). Use the returned id with the /account/{accountRegNo}/webhook/{webhookId}/auth endpoints to attach outbound authentication.

Event types

• new_document — sent when a new document is received/created for an account.

• document_delivery — sent when a document's delivery status changes.

Delivery (webhook usage)

Events are delivered as an HTTP POST with a JSON body to the configured url (which must be https). Your endpoint should respond with a 2xx status code; the delivery request times out after 10 seconds. If outbound authentication is configured (see /account/{accountRegNo}/webhook/{webhookId}/auth) it is applied as request headers on every delivery. The delivered payload is described by the webhookEvent callback below.

Authorizations

api_keyjwt

AuthorizationstringRequired

Path parameters

accountRegNostringRequired

Account registration number issued by Qvalia

Body

application/json

urlstring · uriRequired

HTTPS endpoint that will receive webhook events

Example: https://example.com/webhooks/qvalia

Responses

200

OK

application/json

idstring · uuidOptionalExample: a1b2c3d4-5678-90ab-cdef-1234567890ab

urlstringOptionalExample: https://example.com/webhooks/qvalia

typesstring[]OptionalExample: ["new_document","document_delivery"]

accountRegNostringOptionalExample: SE1234567890

401

Unauthorized

text/plain

422

Unprocessable Entity

application/json

500

Internal Server Error

application/json

put/account/{accountRegNo}/webhook/configure

HTTPcURLJavaScriptPython

PUT /account/{accountRegNo}/webhook/configure HTTP/1.1
Host: api-qa.qvalia.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 90

{
  "url": "https://example.com/webhooks/qvalia",
  "types": [
    "new_document",
    "document_delivery"
  ]
}

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "url": "https://example.com/webhooks/qvalia",
  "types": [
    "new_document",
    "document_delivery"
  ],
  "accountRegNo": "SE1234567890"
}

Delete Webhook Configuration

delete

https://api-qa.qvalia.comhttps://api.qvalia.com

/account/{accountRegNo}/webhook/configure

An API to DELETE the webhook subscription for your Partner account.

This removes the subscription and any attached outbound authentication.

Partner or Partners Account

Partners can configure their own web hooks through /partner/{partnerRegNo}/webhook/... URI, or their child accounts using /partner/{partnerRegNo}/account/{accountRegNo}/webhook/.... The latter is useful if you want to scope the subscription to a single account.

parameter accountRegNo is only required for child accounts, and should be omitted for the Partner account itself.

Authorizations

api_keyjwt

AuthorizationstringRequired

Path parameters

accountRegNostringRequired

Account registration number issued by Qvalia

Responses

204

No Content

text/plain

stringOptionalExample: No Content

401

Unauthorized

text/plain

500

Internal Server Error

application/json

delete/account/{accountRegNo}/webhook/configure

HTTPcURLJavaScriptPython

DELETE /account/{accountRegNo}/webhook/configure HTTP/1.1
Host: api-qa.qvalia.com
Authorization: YOUR_API_KEY
Accept: */*

No Content

Get Webhook Authentication

get

https://api-qa.qvalia.comhttps://api.qvalia.com

/account/{accountRegNo}/webhook/{webhookId}/auth

An API to fetch (GET) the outbound authentication type configured for your account's webhook subscription. Secrets are never returned.

Authorizations

api_keyjwt

AuthorizationstringRequired

Path parameters

accountRegNostringRequired

Account registration number issued by Qvalia

webhookIdstring · uuidRequired

Webhook identifier returned by PUT /webhook/configure, e.g. "a1b2c3d4-5678-90ab-cdef-1234567890ab"

Responses

200

OK

application/json

typestring · enumOptionalExample: api_keyPossible values:

204

No Content

text/plain

401

Unauthorized

text/plain

500

Internal Server Error

application/json

get/account/{accountRegNo}/webhook/{webhookId}/auth

HTTPcURLJavaScriptPython

GET /account/{accountRegNo}/webhook/{webhookId}/auth HTTP/1.1
Host: api-qa.qvalia.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "type": "api_key"
}

Set Webhook Authentication

post

https://api-qa.qvalia.comhttps://api.qvalia.com

/account/{accountRegNo}/webhook/{webhookId}/auth

An API to set (POST) the outbound authentication applied to webhook deliveries for your Partner account's subscription.

{webhookId} must match the id returned by PUT /partner/{partnerRegNo}/account/{accountRegNo}/webhook/configure.

Provide exactly one of the supported auth types:

• oauth — client-credentials. Qvalia fetches a Bearer token from tokenUrl using clientId/clientSecret at delivery time.

• api_key — sent as a request header (header, default X-API-Key) with value.

• basic — HTTP Basic auth using username/password. The password must be at least 16 characters and contain an uppercase letter, a lowercase letter, a digit and a special character.

Authorizations

api_keyjwt

AuthorizationstringRequired

Path parameters

accountRegNostringRequired

Account registration number issued by Qvalia

webhookIdstring · uuidRequired

Webhook identifier returned by PUT /webhook/configure, e.g. "a1b2c3d4-5678-90ab-cdef-1234567890ab"

Body

application/json

or

or

Responses

200

OK

application/json

typestring · enumOptionalExample: api_keyPossible values:

401

Unauthorized

text/plain

404

Not Found

text/plain

422

Unprocessable Entity

application/json

500

Internal Server Error

application/json

post/account/{accountRegNo}/webhook/{webhookId}/auth

HTTPcURLJavaScriptPython

POST /account/{accountRegNo}/webhook/{webhookId}/auth HTTP/1.1
Host: api-qa.qvalia.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 106

{
  "type": "oauth",
  "clientId": "text",
  "clientSecret": "text",
  "tokenUrl": "https://auth.example.com/oauth/token"
}

{
  "type": "api_key"
}

Delete Webhook Authentication

delete

https://api-qa.qvalia.comhttps://api.qvalia.com

/account/{accountRegNo}/webhook/{webhookId}/auth

An API to DELETE the outbound authentication from your account's webhook subscription. The subscription itself is kept; deliveries are sent without auth headers afterwards.

Authorizations

api_keyjwt

AuthorizationstringRequired

Path parameters

accountRegNostringRequired

Account registration number issued by Qvalia

webhookIdstring · uuidRequired

Webhook identifier returned by PUT /webhook/configure, e.g. "a1b2c3d4-5678-90ab-cdef-1234567890ab"

Responses

204

No Content

text/plain

stringOptionalExample: No Content

401

Unauthorized

text/plain

500

Internal Server Error

application/json

delete/account/{accountRegNo}/webhook/{webhookId}/auth

HTTPcURLJavaScriptPython

DELETE /account/{accountRegNo}/webhook/{webhookId}/auth HTTP/1.1
Host: api-qa.qvalia.com
Authorization: YOUR_API_KEY
Accept: */*

No Content