> For the complete documentation index, see [llms.txt](https://api.qvalia.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.qvalia.io/api-documentation/apis/account-api/webhook-api.md). # Webhook API Operations related to Web hooks ## Get Webhook Configuration > 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. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Account API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-qa.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]},{"jwt":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"},"jwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication. The Authorization header must be set as:\nAuthorization: Bearer \nObtain a token via POST /token/{accountRegNo}.\n"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Account registration number issued by Qvalia"}},"responses":{"NoContent":{"description":"No Content","content":{"text/plain":{"schema":{"type":"string"}}}},"Unauthorized":{"description":"Unauthorized","content":{"text/plain":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"type":{"type":"string"},"data":{"type":"string"}}}}}}}},"paths":{"/account/{accountRegNo}/webhook/configure":{"get":{"tags":["Webhook API"],"summary":"Get Webhook Configuration","description":"An API to fetch (GET) the webhook subscription for your Partner account.\n\n### Partner or Partners Account\nPartners can configure their own web hooks through `/partner/{partnerRegNo}/webhook/...` URI, or their child accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.\nThe latter is useful if you want to scope the subscription to a single account.\n### parameter `accountRegNo` is only required for child accounts, and should be omitted for the Partner account itself.","operationId":"account/get-webhook-config","parameters":[{"$ref":"#/components/parameters/accountRegNo"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"types":{"type":"array","items":{"type":"string"}},"accountRegNo":{"type":"string"},"enabled":{"type":"boolean"},"authType":{"type":"string","nullable":true,"enum":["oauth","api_key","basic"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Configure Webhook > 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. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Account API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-qa.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]},{"jwt":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"},"jwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication. The Authorization header must be set as:\nAuthorization: Bearer \nObtain a token via POST /token/{accountRegNo}.\n"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Account registration number issued by Qvalia"}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"text/plain":{"schema":{"type":"string"}}}},"UnprocessableEntity":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"type":{"type":"string"},"data":{"type":"string"},"metadata":{"type":"object","properties":{}}}}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"type":{"type":"string"},"data":{"type":"string"}}}}}}}},"paths":{"/account/{accountRegNo}/webhook/configure":{"put":{"tags":["Webhook API"],"summary":"Configure Webhook","description":"An API to create or update (PUT) the webhook subscription for your account.\n\nAn account has a single webhook subscription. The first `PUT` creates it and\nreturns a generated webhook `id` (a UUID v4); subsequent `PUT` requests update\nthe same subscription (its `url` and/or `types`). Use the returned `id` with the\n`/account/{accountRegNo}/webhook/{webhookId}/auth` endpoints to attach outbound\nauthentication.\n\n### Event types\n\n- `new_document` — sent when a new document is received/created for an account.\n- `document_delivery` — sent when a document's delivery status changes.\n\n### Delivery (webhook usage)\n\nEvents are delivered as an HTTP `POST` with a JSON body to the configured `url`\n(which must be `https`). Your endpoint should respond with a `2xx` status code;\nthe delivery request times out after 10 seconds. If outbound authentication is\nconfigured (see `/account/{accountRegNo}/webhook/{webhookId}/auth`) it is applied\nas request headers on every delivery. The delivered payload is described by the\n`webhookEvent` callback below.","operationId":"account/put-webhook-config","parameters":[{"$ref":"#/components/parameters/accountRegNo"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","types"],"properties":{"url":{"type":"string","format":"uri","description":"HTTPS endpoint that will receive webhook events"},"types":{"type":"array","minItems":1,"items":{"type":"string","enum":["new_document","document_delivery"]}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"types":{"type":"array","items":{"type":"string"}},"accountRegNo":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"500":{"$ref":"#/components/responses/InternalServerError"}},"callbacks":{"webhookEvent":{"{$request.body#/url}":{"post":{"summary":"Webhook event delivered to your endpoint","description":"Qvalia POSTs this JSON payload to your configured `url` when a subscribed\nevent occurs. Your endpoint should respond with a `2xx` status code; the\nrequest times out after 10 seconds. Any configured outbound authentication\n(see `/partner/{partnerRegNo}/webhook/{webhookId}/auth`) is applied as\nrequest headers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"eventType":{"type":"string","enum":["new_document","document_delivery"]},"accountRegNo":{"type":"string"},"documentType":{"type":"string","description":"e.g. Invoice, CreditNote, Order"},"integrationId":{"type":"string","format":"uuid","description":"Qvalia unique identifier for the transaction/message"},"direction":{"type":"string","enum":["incoming","outgoing"]},"occurredAt":{"type":"string","format":"date-time"}}}}}},"responses":{"2XX":{"description":"Event acknowledged by your endpoint"}}}}}}}}}} ``` ## Delete Webhook Configuration > 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. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Account API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-qa.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]},{"jwt":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"},"jwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication. The Authorization header must be set as:\nAuthorization: Bearer \nObtain a token via POST /token/{accountRegNo}.\n"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Account registration number issued by Qvalia"}},"responses":{"NoContent":{"description":"No Content","content":{"text/plain":{"schema":{"type":"string"}}}},"Unauthorized":{"description":"Unauthorized","content":{"text/plain":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"type":{"type":"string"},"data":{"type":"string"}}}}}}}},"paths":{"/account/{accountRegNo}/webhook/configure":{"delete":{"tags":["Webhook API"],"summary":"Delete Webhook Configuration","description":"An API to DELETE the webhook subscription for your Partner account.\n\nThis removes the subscription and any attached outbound authentication.\n\n### Partner or Partners Account\nPartners can configure their own web hooks through `/partner/{partnerRegNo}/webhook/...` URI, or their child accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.\nThe latter is useful if you want to scope the subscription to a single account.\n### parameter `accountRegNo` is only required for child accounts, and should be omitted for the Partner account itself.","operationId":"account/delete-webhook-config","parameters":[{"$ref":"#/components/parameters/accountRegNo"}],"responses":{"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Get Webhook Authentication > An API to fetch (GET) the outbound authentication type configured for your\ > account's webhook subscription. Secrets are never returned. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Account API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-qa.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]},{"jwt":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"},"jwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication. The Authorization header must be set as:\nAuthorization: Bearer \nObtain a token via POST /token/{accountRegNo}.\n"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Account registration number issued by Qvalia"},"webhookId":{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook identifier returned by PUT /webhook/configure, e.g. \"a1b2c3d4-5678-90ab-cdef-1234567890ab\""}},"responses":{"NoContent":{"description":"No Content","content":{"text/plain":{"schema":{"type":"string"}}}},"Unauthorized":{"description":"Unauthorized","content":{"text/plain":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"type":{"type":"string"},"data":{"type":"string"}}}}}}}},"paths":{"/account/{accountRegNo}/webhook/{webhookId}/auth":{"get":{"tags":["Webhook API"],"summary":"Get Webhook Authentication","description":"An API to fetch (GET) the outbound authentication type configured for your\naccount's webhook subscription. Secrets are never returned.","operationId":"account/get-webhook-auth","parameters":[{"$ref":"#/components/parameters/accountRegNo"},{"$ref":"#/components/parameters/webhookId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["oauth","api_key","basic"]}}}}}},"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Set Webhook Authentication > 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 \`type\`s:\ > \ > \- \`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. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Account API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-qa.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]},{"jwt":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"},"jwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication. The Authorization header must be set as:\nAuthorization: Bearer \nObtain a token via POST /token/{accountRegNo}.\n"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Account registration number issued by Qvalia"},"webhookId":{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook identifier returned by PUT /webhook/configure, e.g. \"a1b2c3d4-5678-90ab-cdef-1234567890ab\""}},"responses":{"Unauthorized":{"description":"Unauthorized","content":{"text/plain":{"schema":{"type":"string"}}}},"NotFound":{"description":"Not Found","content":{"text/plain":{"schema":{"type":"string"}}}},"UnprocessableEntity":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"type":{"type":"string"},"data":{"type":"string"},"metadata":{"type":"object","properties":{}}}}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"type":{"type":"string"},"data":{"type":"string"}}}}}}}},"paths":{"/account/{accountRegNo}/webhook/{webhookId}/auth":{"post":{"tags":["Webhook API"],"summary":"Set Webhook Authentication","description":"An API to set (POST) the outbound authentication applied to webhook deliveries\nfor your Partner account's subscription.\n\n`{webhookId}` must match the `id` returned by `PUT /partner/{partnerRegNo}/account/{accountRegNo}/webhook/configure`.\n\nProvide exactly one of the supported auth `type`s:\n\n- `oauth` — client-credentials. Qvalia fetches a Bearer token from `tokenUrl`\n using `clientId`/`clientSecret` at delivery time.\n- `api_key` — sent as a request header (`header`, default `X-API-Key`) with `value`.\n- `basic` — HTTP Basic auth using `username`/`password`. The `password` must be at\n least 16 characters and contain an uppercase letter, a lowercase letter, a digit\n and a special character.","operationId":"account/post-webhook-auth","parameters":[{"$ref":"#/components/parameters/accountRegNo"},{"$ref":"#/components/parameters/webhookId"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["type","clientId","clientSecret","tokenUrl"],"properties":{"type":{"type":"string","enum":["oauth"]},"clientId":{"type":"string"},"clientSecret":{"type":"string"},"tokenUrl":{"type":"string","format":"uri"}}},{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["api_key"]},"header":{"type":"string","default":"X-API-Key"},"value":{"type":"string"}}},{"type":"object","required":["type","username","password"],"properties":{"type":{"type":"string","enum":["basic"]},"username":{"type":"string"},"password":{"type":"string","description":"Minimum 16 characters; must contain uppercase, lowercase, digit and special character."}}}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["oauth","api_key","basic"]}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Delete Webhook Authentication > 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. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Account API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-qa.qvalia.com"},{"url":"https://api.qvalia.com"}],"security":[{"api_key":[]},{"jwt":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","name":"Authorization","in":"header"},"jwt":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT-based authentication. The Authorization header must be set as:\nAuthorization: Bearer \nObtain a token via POST /token/{accountRegNo}.\n"}},"parameters":{"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Account registration number issued by Qvalia"},"webhookId":{"name":"webhookId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Webhook identifier returned by PUT /webhook/configure, e.g. \"a1b2c3d4-5678-90ab-cdef-1234567890ab\""}},"responses":{"NoContent":{"description":"No Content","content":{"text/plain":{"schema":{"type":"string"}}}},"Unauthorized":{"description":"Unauthorized","content":{"text/plain":{"schema":{"type":"string"}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"type":{"type":"string"},"data":{"type":"string"}}}}}}}},"paths":{"/account/{accountRegNo}/webhook/{webhookId}/auth":{"delete":{"tags":["Webhook API"],"summary":"Delete Webhook Authentication","description":"An API to DELETE the outbound authentication from your account's webhook\nsubscription. The subscription itself is kept; deliveries are sent without auth\nheaders afterwards.","operationId":"account/delete-webhook-auth","parameters":[{"$ref":"#/components/parameters/accountRegNo"},{"$ref":"#/components/parameters/webhookId"}],"responses":{"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://api.qvalia.io/api-documentation/apis/account-api/webhook-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.