> 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/partner-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 this endpoint, 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. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner registration number issued by Qvalia"}},"responses":{"WebhookConfigureFetched":{"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"]},"signing":{"type":"object","nullable":true,"description":"Signing state for this subscription, or `null` when deliveries are\nunsigned. This block carries ids and dates only, never a secret value.","properties":{"algorithm":{"type":"string","enum":["hmac-sha256"]},"secrets":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSigningSecretInfo"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"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"}}}}}}},"schemas":{"WebhookSigningSecretInfo":{"type":"object","description":"A signing secret on a subscription, described without its value. Secrets are\nstored encrypted and are only ever shown once, when issued.","properties":{"id":{"type":"string","description":"Identifier for the secret. Not itself a secret."},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"When this secret stops verifying. `null` for the current secret, which does\nnot expire; a date on a secret being rotated away from."},"active":{"type":"boolean","description":"Whether the secret is still used to sign deliveries."}}}}},"paths":{"/partner/{partnerRegNo}/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 this endpoint, or their\nchild accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.\nThe latter is useful if you want to scope the subscription to a single account.","operationId":"partner/get-webhook-config","parameters":[{"$ref":"#/components/parameters/partnerRegNo"}],"responses":{"200":{"$ref":"#/components/responses/WebhookConfigureFetched"},"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 Partner\ > account.\ > \ > \### Partner or Partners Account\ > Partners can configure their own web hooks through this endpoint, 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.\ > \ > A partner 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\ > \`/partner/{partnerRegNo}/webhook/{webhookId}/auth\` endpoints to attach outbound\ > authentication.\ > \ > A \`PUT\` that creates the subscription returns a \`signingSecret\` in clear text in\ > that response only. Store it; see \`/partner/{partnerRegNo}/webhook/{webhookId}/secret\`\ > to rotate it or to obtain one for an older subscription.\ > \ > \### 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.\ > \- \`document\_delayed\` — sent when a delivery is being retried and has not finished.\ > \- \`document\_error\` — sent when a document's delivery fails.\ > \ > \### 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 \`/partner/{partnerRegNo}/webhook/{webhookId}/auth\`) it is applied\ > as request headers on every delivery. The delivered payload is described by the\ > \`webhookEvent\` callback below.\ > \ > Every delivery carries \`X-Qvalia-Event-Id\`, and \`X-Qvalia-Signature\` once the\ > subscription has a signing secret — see\ > \`/partner/{partnerRegNo}/webhook/{webhookId}/secret\`.\ > \ > Delivery is at-least-once. Make your endpoint idempotent and dedupe on \`eventId\`,\ > which is identical across redeliveries of the same event; do not dedupe on the\ > whole body, which differs in \`status.updatedAt\`.\ > \ > A failed delivery — non-2xx, timeout or unreachable — is recorded against the\ > document but not retried, so a missed event is permanently lost. Webhooks cannot\ > be your only source of truth: keep polling the Transaction API as a safety net.\ > Signing and \`eventId\` deduplication make a delivery you receive trustworthy;\ > neither makes delivery guaranteed.\ > \ > \### Delivered payload\ > \ > Each delivery is a single flat JSON object: the event fields (\`eventType\`,\ > \`accountRegNo\`, \`documentType\`, \`direction\`, \`integrationId\`, \`occurredAt\`) and\ > the document detail (\`documentId\`, \`globalTransactionId\`, \`status\`, \`error\`,\ > \`peppol\_metadata\`) on the same level. Full schema in the \`webhookEvent\` callback\ > below.\ > \ > \`new\_document\`:\ > \ > \`\`\`json\ > {\ > "eventId": "4d1c9f84-3a2b-5c6d-9e0f-1a2b3c4d5e6f",\ > "eventType": "new\_document",\ > "accountRegNo": "SE5560004755",\ > "documentType": "Invoice",\ > "direction": "outgoing",\ > "integrationId": "6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4",\ > "occurredAt": "2026-08-19T09:25:36.512Z",\ > "documentId": "123456-INV",\ > "globalTransactionId": "6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4",\ > "status": {\ > "event": "message-log/create",\ > "deliveryMethod": "peppol",\ > "updatedAt": "2026-08-19T09:25:37.228Z"\ > },\ > "peppol\_metadata": {\ > "messageId": "9cab8ba5-d2a4-45d0-842d-8ede91dcac9f\@QVALIA-PSE000094",\ > "accessPoint": "PSE000094",\ > "docTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",\ > "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",\ > "exchangeDateTime": "2026-08-19T09:25:34.226Z"\ > }\ > }\ > \`\`\`\ > \ > \`document\_delivery\` — a status transition on a document already announced via\ > \`new\_document\`; \`documentId\` is often absent at this stage:\ > \ > \`\`\`json\ > {\ > "eventId": "8b3e1a07-6c5d-5e4f-9a2b-7c8d9e0f1a2b",\ > "eventType": "document\_delivery",\ > "accountRegNo": "SE5560004755",\ > "documentType": "Invoice",\ > "direction": "outgoing",\ > "integrationId": "6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4",\ > "occurredAt": "2026-08-19T09:26:10.104Z",\ > "globalTransactionId": "6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4",\ > "status": {\ > "status": "processed",\ > "event": "message-log/update",\ > "deliveryMethod": "peppol",\ > "updatedAt": "2026-08-19T09:26:09.881Z"\ > },\ > "peppol\_metadata": {\ > "messageId": "9cab8ba5-d2a4-45d0-842d-8ede91dcac9f\@QVALIA-PSE000094",\ > "accessPoint": "PSE000094",\ > "docTypeId": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",\ > "processId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",\ > "exchangeDateTime": "2026-08-19T09:25:34.226Z"\ > }\ > }\ > \`\`\`\ > \ > \`document\_error\` — delivery failed; \`error\` carries a human-readable reason:\ > \ > \`\`\`json\ > {\ > "eventId": "c71f2d93-4e8a-5b6c-8d7e-2f3a4b5c6d7e",\ > "eventType": "document\_error",\ > "accountRegNo": "SE5560004755",\ > "documentType": "Invoice",\ > "direction": "outgoing",\ > "integrationId": "6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4",\ > "occurredAt": "2026-08-19T09:26:10.104Z",\ > "globalTransactionId": "6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4",\ > "status": {\ > "status": "error",\ > "event": "message-log/error",\ > "deliveryMethod": "peppol",\ > "updatedAt": "2026-08-19T09:26:09.881Z"\ > },\ > "error": "Peppol validation failed: invoice does not conform to UBL 2.1",\ > "peppol\_metadata": null\ > }\ > \`\`\` ````json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner registration number issued by Qvalia"}},"requestBodies":{"WebhookConfigure":{"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","document_delayed","document_error"]}}}}}}}},"responses":{"WebhookConfigureCreated":{"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"},"signingSecret":{"type":"string","description":"Secret used to sign deliveries to this subscription (HMAC-SHA256).\n\n**Returned only when this `PUT` created the subscription, and only in\nthis one response** — we store it encrypted and cannot show it again.\nStore it now. Lost it, or updating a subscription created before\nsigning existed? Use `POST .../webhook/{webhookId}/secret`."},"signingSecretId":{"type":"string","description":"Identifier for the secret above, for use in support and audit. Not itself a secret."},"signatureAlgorithm":{"type":"string","enum":["hmac-sha256"]}}}}}},"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"}}}}}}},"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\nis applied as request headers.\n\nWhen the subscription has a signing secret, the delivery is also signed —\nsee `POST /partner/{partnerRegNo}/webhook/{webhookId}/secret`.","parameters":[{"name":"X-Qvalia-Event-Id","in":"header","required":true,"description":"Identifies the event, not the delivery attempt: redeliveries of the same\nevent carry the same value. Mirrors `eventId` in the body. Deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"X-Qvalia-Signature","in":"header","required":false,"description":"HMAC-SHA256 signature of the delivered body, in the form\n`t=,v1=`. Recompute\n`HMAC-SHA256(secret, \".\")` over the **raw** bytes received\nand compare in constant time. More than one `v1=` part is sent while a\nsecret rotation overlap is open — any one matching is a pass. Ignore\nparts whose prefix you do not recognise. Only sent when the subscription\nhas a signing secret.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["eventId","eventType","accountRegNo"],"properties":{"eventId":{"type":"string","format":"uuid","description":"Identifies the event, not the delivery attempt. Derived from the\nevent content, so every redelivery of the same event carries the\nsame value — deduplicate on it. Also sent as the\n`X-Qvalia-Event-Id` header."},"eventType":{"type":"string","enum":["new_document","document_delivery","document_delayed","document_error"]},"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"},"documentId":{"type":"string","description":"Document number (e.g. invoice number). Present on `new_document`;\nmay be absent on `document_delivery`/`document_error` when the\nupstream delivery channel does not report one."},"globalTransactionId":{"type":"string","format":"uuid","description":"Qvalia's platform-wide transaction id for this document exchange. Absent if not available for this event."},"status":{"type":"object","description":"Delivery-lifecycle detail for this event. Present on all event types.","properties":{"status":{"type":"string","description":"Delivery status reported by the upstream delivery channel (Peppol,\nemail, print, …).\n\nValues currently emitted, and whether each is final:\n\n- `pending` (non-final) — logged; nothing attempted yet. Also the\n upstream column default.\n- `warning` (non-final) — reopened by a rules-processor reset.\n- `delayed` (non-final) — being retried: a Peppol send still inside\n its retry window. Another event **will** follow. Not a failure!\n- `processed` (final) — delivered successfully.\n- `processed_with_warning` (final) — delivered, but something about\n the exchange is worth flagging.\n- `error` (non-final) — delivery failed; the top-level `error` carries\n the reason. Message resend might follow.\n- *absent* — no status reported for this event. Documents entering\n through the Public API announce themselves without one.\n\n**To tell a retry from a real failure, branch on this field rather\nthan on the text of `error`:** `delayed` means another attempt is\ncoming, `error` means the send has stopped for good."},"event":{"type":"string","description":"The internal message-log lifecycle event that triggered this webhook.","enum":["message-log/create","message-log/update","message-log/delayed","message-log/error"]},"deliveryMethod":{"type":"string","description":"Delivery method used for this document, e.g. `peppol`, `print`, `email`,\n`api`, `internetbank`, `kivra`, `billo`, `minameddelanden`, `postal`,\n`dynamic_routing`. Like `status`, an open set. May be absent."},"updatedAt":{"type":"string","format":"date-time"}}},"error":{"type":"string","description":"Error message describing the delivery failure. Only present when `eventType` is `document_error`."},"peppol_metadata":{"type":"object","nullable":true,"description":"Peppol exchange detail. `null` when `status.deliveryMethod` is not `peppol`.","properties":{"messageId":{"type":"string"},"accessPoint":{"type":"string"},"docTypeId":{"type":"string"},"processId":{"type":"string"},"exchangeDateTime":{"type":"string","format":"date-time"}}}}}}}},"responses":{"2XX":{"description":"Event acknowledged by your endpoint"},"4XX":{"description":"Event not acknowledged by your endpoint"}},"security":[{}]}}}}},"paths":{"/partner/{partnerRegNo}/webhook/configure":{"put":{"tags":["Webhook API"],"summary":"Configure Webhook","description":"An API to create or update (PUT) the webhook subscription for your Partner\naccount.\n\n### Partner or Partners Account\nPartners can configure their own web hooks through this endpoint, or their\nchild accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.\nThe latter is useful if you want to scope the subscription to a single account.\n\nA partner 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`/partner/{partnerRegNo}/webhook/{webhookId}/auth` endpoints to attach outbound\nauthentication.\n\nA `PUT` that creates the subscription returns a `signingSecret` in clear text in\nthat response only. Store it; see `/partner/{partnerRegNo}/webhook/{webhookId}/secret`\nto rotate it or to obtain one for an older subscription.\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- `document_delayed` — sent when a delivery is being retried and has not finished.\n- `document_error` — sent when a document's delivery fails.\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 `/partner/{partnerRegNo}/webhook/{webhookId}/auth`) it is applied\nas request headers on every delivery. The delivered payload is described by the\n`webhookEvent` callback below.\n\nEvery delivery carries `X-Qvalia-Event-Id`, and `X-Qvalia-Signature` once the\nsubscription has a signing secret — see\n`/partner/{partnerRegNo}/webhook/{webhookId}/secret`.\n\nDelivery is at-least-once. Make your endpoint idempotent and dedupe on `eventId`,\nwhich is identical across redeliveries of the same event; do not dedupe on the\nwhole body, which differs in `status.updatedAt`.\n\nA failed delivery — non-2xx, timeout or unreachable — is recorded against the\ndocument but not retried, so a missed event is permanently lost. Webhooks cannot\nbe your only source of truth: keep polling the Transaction API as a safety net.\nSigning and `eventId` deduplication make a delivery you receive trustworthy;\nneither makes delivery guaranteed.\n\n### Delivered payload\n\nEach delivery is a single flat JSON object: the event fields (`eventType`,\n`accountRegNo`, `documentType`, `direction`, `integrationId`, `occurredAt`) and\nthe document detail (`documentId`, `globalTransactionId`, `status`, `error`,\n`peppol_metadata`) on the same level. Full schema in the `webhookEvent` callback\nbelow.\n\n`new_document`:\n\n```json\n{\n \"eventId\": \"4d1c9f84-3a2b-5c6d-9e0f-1a2b3c4d5e6f\",\n \"eventType\": \"new_document\",\n \"accountRegNo\": \"SE5560004755\",\n \"documentType\": \"Invoice\",\n \"direction\": \"outgoing\",\n \"integrationId\": \"6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4\",\n \"occurredAt\": \"2026-08-19T09:25:36.512Z\",\n \"documentId\": \"123456-INV\",\n \"globalTransactionId\": \"6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4\",\n \"status\": {\n \"event\": \"message-log/create\",\n \"deliveryMethod\": \"peppol\",\n \"updatedAt\": \"2026-08-19T09:25:37.228Z\"\n },\n \"peppol_metadata\": {\n \"messageId\": \"9cab8ba5-d2a4-45d0-842d-8ede91dcac9f@QVALIA-PSE000094\",\n \"accessPoint\": \"PSE000094\",\n \"docTypeId\": \"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1\",\n \"processId\": \"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0\",\n \"exchangeDateTime\": \"2026-08-19T09:25:34.226Z\"\n }\n}\n```\n\n`document_delivery` — a status transition on a document already announced via\n`new_document`; `documentId` is often absent at this stage:\n\n```json\n{\n \"eventId\": \"8b3e1a07-6c5d-5e4f-9a2b-7c8d9e0f1a2b\",\n \"eventType\": \"document_delivery\",\n \"accountRegNo\": \"SE5560004755\",\n \"documentType\": \"Invoice\",\n \"direction\": \"outgoing\",\n \"integrationId\": \"6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4\",\n \"occurredAt\": \"2026-08-19T09:26:10.104Z\",\n \"globalTransactionId\": \"6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4\",\n \"status\": {\n \"status\": \"processed\",\n \"event\": \"message-log/update\",\n \"deliveryMethod\": \"peppol\",\n \"updatedAt\": \"2026-08-19T09:26:09.881Z\"\n },\n \"peppol_metadata\": {\n \"messageId\": \"9cab8ba5-d2a4-45d0-842d-8ede91dcac9f@QVALIA-PSE000094\",\n \"accessPoint\": \"PSE000094\",\n \"docTypeId\": \"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1\",\n \"processId\": \"urn:fdc:peppol.eu:2017:poacc:billing:01:1.0\",\n \"exchangeDateTime\": \"2026-08-19T09:25:34.226Z\"\n }\n}\n```\n\n`document_error` — delivery failed; `error` carries a human-readable reason:\n\n```json\n{\n \"eventId\": \"c71f2d93-4e8a-5b6c-8d7e-2f3a4b5c6d7e\",\n \"eventType\": \"document_error\",\n \"accountRegNo\": \"SE5560004755\",\n \"documentType\": \"Invoice\",\n \"direction\": \"outgoing\",\n \"integrationId\": \"6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4\",\n \"occurredAt\": \"2026-08-19T09:26:10.104Z\",\n \"globalTransactionId\": \"6b928ef1-fb0d-4b9a-a56f-b5dbca7a0fd4\",\n \"status\": {\n \"status\": \"error\",\n \"event\": \"message-log/error\",\n \"deliveryMethod\": \"peppol\",\n \"updatedAt\": \"2026-08-19T09:26:09.881Z\"\n },\n \"error\": \"Peppol validation failed: invoice does not conform to UBL 2.1\",\n \"peppol_metadata\": null\n}\n```","operationId":"partner/put-webhook-config","parameters":[{"$ref":"#/components/parameters/partnerRegNo"}],"requestBody":{"$ref":"#/components/requestBodies/WebhookConfigure"},"responses":{"200":{"$ref":"#/components/responses/WebhookConfigureCreated"},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"500":{"$ref":"#/components/responses/InternalServerError"}},"callbacks":{"webhookEvent":{"$ref":"#/components/callbacks/webhookEvent"}}}}}} ```` ## 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 this endpoint, 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. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner 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":{"/partner/{partnerRegNo}/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 this endpoint, or their\nchild accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.\nThe latter is useful if you want to scope the subscription to a single account.","operationId":"partner/delete-webhook-config","parameters":[{"$ref":"#/components/parameters/partnerRegNo"}],"responses":{"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Get Webhook Configuration for child account > An API to fetch (GET) the webhook subscription scoped to a single child account\ > under your Partner account. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner registration number issued by Qvalia"},"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Account registration number issued by Qvalia"}},"responses":{"WebhookConfigureFetched":{"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"]},"signing":{"type":"object","nullable":true,"description":"Signing state for this subscription, or `null` when deliveries are\nunsigned. This block carries ids and dates only, never a secret value.","properties":{"algorithm":{"type":"string","enum":["hmac-sha256"]},"secrets":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSigningSecretInfo"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"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"}}}}}}},"schemas":{"WebhookSigningSecretInfo":{"type":"object","description":"A signing secret on a subscription, described without its value. Secrets are\nstored encrypted and are only ever shown once, when issued.","properties":{"id":{"type":"string","description":"Identifier for the secret. Not itself a secret."},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"When this secret stops verifying. `null` for the current secret, which does\nnot expire; a date on a secret being rotated away from."},"active":{"type":"boolean","description":"Whether the secret is still used to sign deliveries."}}}}},"paths":{"/partner/{partnerRegNo}/account/{accountRegNo}/webhook/configure":{"get":{"tags":["Webhook API"],"summary":"Get Webhook Configuration for child account","description":"An API to fetch (GET) the webhook subscription scoped to a single child account\nunder your Partner account.","operationId":"partner/get-account-webhook-config","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/accountRegNo"}],"responses":{"200":{"$ref":"#/components/responses/WebhookConfigureFetched"},"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Configure Webhook for child account > An API to create or update (PUT) the webhook subscription scoped to a single\ > child account under your Partner account.\ > \ > \### Partner or Partners Account\ > Partners can configure their own web hooks through \`/partner/{partnerRegNo}/webhook/...\`,\ > or their child accounts using this endpoint (scoped to a single account).\ > \ > A partner has a single webhook subscription per account. 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\ > \`/partner/{partnerRegNo}/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.\ > \- \`document\_delayed\` — sent when a delivery is being retried and has not finished.\ > \- \`document\_error\` — sent when a document's delivery fails.\ > \ > \### 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 \`/partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/auth\`)\ > it is applied as request headers on every delivery. The delivered payload is a\ > single flat JSON object — see the \`webhookEvent\` callback below for the full\ > schema, and \`/partner/{partnerRegNo}/webhook/configure\` above for worked\ > examples of all three event types.\ > \ > Every delivery carries \`X-Qvalia-Event-Id\`, and \`X-Qvalia-Signature\` once the\ > subscription has a signing secret — see\ > \`/partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/secret\`.\ > \ > Delivery is at-least-once and a failed delivery is not retried; see\ > \`/partner/{partnerRegNo}/webhook/configure\` above for details. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner registration number issued by Qvalia"},"accountRegNo":{"name":"accountRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Account registration number issued by Qvalia"}},"requestBodies":{"WebhookConfigure":{"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","document_delayed","document_error"]}}}}}}}},"responses":{"WebhookConfigureCreated":{"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"},"signingSecret":{"type":"string","description":"Secret used to sign deliveries to this subscription (HMAC-SHA256).\n\n**Returned only when this `PUT` created the subscription, and only in\nthis one response** — we store it encrypted and cannot show it again.\nStore it now. Lost it, or updating a subscription created before\nsigning existed? Use `POST .../webhook/{webhookId}/secret`."},"signingSecretId":{"type":"string","description":"Identifier for the secret above, for use in support and audit. Not itself a secret."},"signatureAlgorithm":{"type":"string","enum":["hmac-sha256"]}}}}}},"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"}}}}}}},"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\nis applied as request headers.\n\nWhen the subscription has a signing secret, the delivery is also signed —\nsee `POST /partner/{partnerRegNo}/webhook/{webhookId}/secret`.","parameters":[{"name":"X-Qvalia-Event-Id","in":"header","required":true,"description":"Identifies the event, not the delivery attempt: redeliveries of the same\nevent carry the same value. Mirrors `eventId` in the body. Deduplicate on it.","schema":{"type":"string","format":"uuid"}},{"name":"X-Qvalia-Signature","in":"header","required":false,"description":"HMAC-SHA256 signature of the delivered body, in the form\n`t=,v1=`. Recompute\n`HMAC-SHA256(secret, \".\")` over the **raw** bytes received\nand compare in constant time. More than one `v1=` part is sent while a\nsecret rotation overlap is open — any one matching is a pass. Ignore\nparts whose prefix you do not recognise. Only sent when the subscription\nhas a signing secret.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["eventId","eventType","accountRegNo"],"properties":{"eventId":{"type":"string","format":"uuid","description":"Identifies the event, not the delivery attempt. Derived from the\nevent content, so every redelivery of the same event carries the\nsame value — deduplicate on it. Also sent as the\n`X-Qvalia-Event-Id` header."},"eventType":{"type":"string","enum":["new_document","document_delivery","document_delayed","document_error"]},"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"},"documentId":{"type":"string","description":"Document number (e.g. invoice number). Present on `new_document`;\nmay be absent on `document_delivery`/`document_error` when the\nupstream delivery channel does not report one."},"globalTransactionId":{"type":"string","format":"uuid","description":"Qvalia's platform-wide transaction id for this document exchange. Absent if not available for this event."},"status":{"type":"object","description":"Delivery-lifecycle detail for this event. Present on all event types.","properties":{"status":{"type":"string","description":"Delivery status reported by the upstream delivery channel (Peppol,\nemail, print, …).\n\nValues currently emitted, and whether each is final:\n\n- `pending` (non-final) — logged; nothing attempted yet. Also the\n upstream column default.\n- `warning` (non-final) — reopened by a rules-processor reset.\n- `delayed` (non-final) — being retried: a Peppol send still inside\n its retry window. Another event **will** follow. Not a failure!\n- `processed` (final) — delivered successfully.\n- `processed_with_warning` (final) — delivered, but something about\n the exchange is worth flagging.\n- `error` (non-final) — delivery failed; the top-level `error` carries\n the reason. Message resend might follow.\n- *absent* — no status reported for this event. Documents entering\n through the Public API announce themselves without one.\n\n**To tell a retry from a real failure, branch on this field rather\nthan on the text of `error`:** `delayed` means another attempt is\ncoming, `error` means the send has stopped for good."},"event":{"type":"string","description":"The internal message-log lifecycle event that triggered this webhook.","enum":["message-log/create","message-log/update","message-log/delayed","message-log/error"]},"deliveryMethod":{"type":"string","description":"Delivery method used for this document, e.g. `peppol`, `print`, `email`,\n`api`, `internetbank`, `kivra`, `billo`, `minameddelanden`, `postal`,\n`dynamic_routing`. Like `status`, an open set. May be absent."},"updatedAt":{"type":"string","format":"date-time"}}},"error":{"type":"string","description":"Error message describing the delivery failure. Only present when `eventType` is `document_error`."},"peppol_metadata":{"type":"object","nullable":true,"description":"Peppol exchange detail. `null` when `status.deliveryMethod` is not `peppol`.","properties":{"messageId":{"type":"string"},"accessPoint":{"type":"string"},"docTypeId":{"type":"string"},"processId":{"type":"string"},"exchangeDateTime":{"type":"string","format":"date-time"}}}}}}}},"responses":{"2XX":{"description":"Event acknowledged by your endpoint"},"4XX":{"description":"Event not acknowledged by your endpoint"}},"security":[{}]}}}}},"paths":{"/partner/{partnerRegNo}/account/{accountRegNo}/webhook/configure":{"put":{"tags":["Webhook API"],"summary":"Configure Webhook for child account","description":"An API to create or update (PUT) the webhook subscription scoped to a single\nchild account under your Partner account.\n\n### Partner or Partners Account\nPartners can configure their own web hooks through `/partner/{partnerRegNo}/webhook/...`,\nor their child accounts using this endpoint (scoped to a single account).\n\nA partner has a single webhook subscription per account. The first `PUT` creates it\nand returns 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`/partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/auth` endpoints\nto attach outbound authentication.\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- `document_delayed` — sent when a delivery is being retried and has not finished.\n- `document_error` — sent when a document's delivery fails.\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 `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/auth`)\nit is applied as request headers on every delivery. The delivered payload is a\nsingle flat JSON object — see the `webhookEvent` callback below for the full\nschema, and `/partner/{partnerRegNo}/webhook/configure` above for worked\nexamples of all three event types.\n\nEvery delivery carries `X-Qvalia-Event-Id`, and `X-Qvalia-Signature` once the\nsubscription has a signing secret — see\n`/partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/secret`.\n\nDelivery is at-least-once and a failed delivery is not retried; see\n`/partner/{partnerRegNo}/webhook/configure` above for details.","operationId":"partner/put-account-webhook-config","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/accountRegNo"}],"requestBody":{"$ref":"#/components/requestBodies/WebhookConfigure"},"responses":{"200":{"$ref":"#/components/responses/WebhookConfigureCreated"},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"500":{"$ref":"#/components/responses/InternalServerError"}},"callbacks":{"webhookEvent":{"$ref":"#/components/callbacks/webhookEvent"}}}}}} ``` ## Delete Webhook Configuration for child account > An API to DELETE the webhook subscription scoped to a single child account\ > under your Partner account.\ > \ > This removes the subscription and any attached outbound authentication. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner registration number issued by Qvalia"},"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":{"/partner/{partnerRegNo}/account/{accountRegNo}/webhook/configure":{"delete":{"tags":["Webhook API"],"summary":"Delete Webhook Configuration for child account","description":"An API to DELETE the webhook subscription scoped to a single child account\nunder your Partner account.\n\nThis removes the subscription and any attached outbound authentication.","operationId":"partner/delete-account-webhook-config","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$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\ > Partner account's webhook subscription. The credential itself is never returned.\ > \ > \### Partner or Partners Account\ > Partners can configure their own web hooks through this endpoint, or their\ > child accounts using \`/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...\`. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner 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":{"WebhookAuthSet":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["oauth","api_key","basic"]}}}}}},"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":{"/partner/{partnerRegNo}/webhook/{webhookId}/auth":{"get":{"tags":["Webhook API"],"summary":"Get Webhook Authentication","description":"An API to fetch (GET) the outbound authentication type configured for your\nPartner account's webhook subscription. The credential itself is never returned.\n\n### Partner or Partners Account\nPartners can configure their own web hooks through this endpoint, or their\nchild accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.","operationId":"partner/get-webhook-auth","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/webhookId"}],"responses":{"200":{"$ref":"#/components/responses/WebhookAuthSet"},"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.\ > \ > \### Partner or Partners Account\ > Partners can configure their own web hooks through this endpoint, or their\ > child accounts using \`/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...\`.\ > \ > \`{webhookId}\` must match the \`id\` returned by \`PUT /partner/{partnerRegNo}/webhook/configure\`.\ > \ > Provide exactly one of the supported auth \`type\`s:\ > \ > \- \`oauth\` — client-credentials. Qvalia fetches a Bearer token from \`tokenUrl\`\ > using \`clientId\`/\`clientSecret\` (and optional \`scope\`) 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 Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner 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\""}},"requestBodies":{"WebhookAuth":{"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"},"scope":{"type":"string","description":"Optional OAuth scope(s) sent with the client-credentials token request."}}},{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["api_key"]},"header":{"type":"string","default":"X-API-Key","description":"Header the API key is sent in.\n\n`X-Qvalia-*` is reserved and rejected: that prefix carries the delivery's\nevent id and HMAC signature, so claiming one would overwrite a security\nheader on your own deliveries.","pattern":"^(?![Xx]-[Qq][Vv][Aa][Ll][Ii][Aa]-).+$"},"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":{"WebhookAuthSet":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["oauth","api_key","basic"]}}}}}},"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":{"/partner/{partnerRegNo}/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### Partner or Partners Account\nPartners can configure their own web hooks through this endpoint, or their\nchild accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.\n\n`{webhookId}` must match the `id` returned by `PUT /partner/{partnerRegNo}/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` (and optional `scope`) 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":"partner/post-webhook-auth","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/webhookId"}],"requestBody":{"$ref":"#/components/requestBodies/WebhookAuth"},"responses":{"200":{"$ref":"#/components/responses/WebhookAuthSet"},"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 Partner account's webhook\ > subscription. The subscription itself is kept; deliveries are sent without auth\ > headers afterwards.\ > \ > \### Partner or Partners Account\ > Partners can configure their own web hooks through this endpoint, or their\ > child accounts using \`/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...\`. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner 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":{"/partner/{partnerRegNo}/webhook/{webhookId}/auth":{"delete":{"tags":["Webhook API"],"summary":"Delete Webhook Authentication","description":"An API to DELETE the outbound authentication from your Partner account's webhook\nsubscription. The subscription itself is kept; deliveries are sent without auth\nheaders afterwards.\n\n### Partner or Partners Account\nPartners can configure their own web hooks through this endpoint, or their\nchild accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.","operationId":"partner/delete-webhook-auth","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/webhookId"}],"responses":{"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Get Webhook Authentication for child account > An API to fetch (GET) the outbound authentication type configured for a child\ > account's webhook subscription under your Partner account. The credential itself is never returned. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner registration number issued by Qvalia"},"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":{"WebhookAuthSet":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["oauth","api_key","basic"]}}}}}},"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":{"/partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/auth":{"get":{"tags":["Webhook API"],"summary":"Get Webhook Authentication for child account","description":"An API to fetch (GET) the outbound authentication type configured for a child\naccount's webhook subscription under your Partner account. The credential itself is never returned.","operationId":"partner/get-account-webhook-auth","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/accountRegNo"},{"$ref":"#/components/parameters/webhookId"}],"responses":{"200":{"$ref":"#/components/responses/WebhookAuthSet"},"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Set Webhook Authentication for child account > An API to set (POST) the outbound authentication applied to webhook deliveries\ > for a child account's subscription under your Partner account.\ > \ > \`{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\` (and optional \`scope\`) 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 Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner registration number issued by Qvalia"},"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\""}},"requestBodies":{"WebhookAuth":{"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"},"scope":{"type":"string","description":"Optional OAuth scope(s) sent with the client-credentials token request."}}},{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["api_key"]},"header":{"type":"string","default":"X-API-Key","description":"Header the API key is sent in.\n\n`X-Qvalia-*` is reserved and rejected: that prefix carries the delivery's\nevent id and HMAC signature, so claiming one would overwrite a security\nheader on your own deliveries.","pattern":"^(?![Xx]-[Qq][Vv][Aa][Ll][Ii][Aa]-).+$"},"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":{"WebhookAuthSet":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["oauth","api_key","basic"]}}}}}},"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":{"/partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/auth":{"post":{"tags":["Webhook API"],"summary":"Set Webhook Authentication for child account","description":"An API to set (POST) the outbound authentication applied to webhook deliveries\nfor a child account's subscription under your Partner account.\n\n`{webhookId}` must match the `id` returned by\n`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` (and optional `scope`) 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":"partner/post-account-webhook-auth","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/accountRegNo"},{"$ref":"#/components/parameters/webhookId"}],"requestBody":{"$ref":"#/components/requestBodies/WebhookAuth"},"responses":{"200":{"$ref":"#/components/responses/WebhookAuthSet"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Delete Webhook Authentication for child account > An API to DELETE the outbound authentication from a child account's webhook\ > subscription under your Partner account. The subscription itself is kept;\ > deliveries are sent without auth headers afterwards. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner registration number issued by Qvalia"},"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":{"/partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/auth":{"delete":{"tags":["Webhook API"],"summary":"Delete Webhook Authentication for child account","description":"An API to DELETE the outbound authentication from a child account's webhook\nsubscription under your Partner account. The subscription itself is kept;\ndeliveries are sent without auth headers afterwards.","operationId":"partner/delete-account-webhook-auth","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/accountRegNo"},{"$ref":"#/components/parameters/webhookId"}],"responses":{"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Get Webhook Signing Secrets > An API to fetch (GET) which signing secrets exist on your Partner account's webhook\ > subscription and when each stops verifying.\ > \ > This endpoint returns ids and dates only, never a secret value.\ > \ > A secret is shown once, in the response that issues it: the \`PUT /partner/{partnerRegNo}/webhook/configure\`\ > that creates the subscription, or \`POST /partner/{partnerRegNo}/webhook/{webhookId}/secret\`. It is stored\ > encrypted and cannot be read back afterwards — if you have lost one, issue a new\ > one with \`POST\`.\ > \ > \### Partner or Partners Account\ > Partners can configure their own web hooks through this endpoint, or their\ > child accounts using \`/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...\`. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner 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":{"WebhookSecretFetched":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"webhookId":{"type":"string","format":"uuid"},"algorithm":{"type":"string","enum":["hmac-sha256"]},"secrets":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSigningSecretInfo"}}}}}}},"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"}}}}}}},"schemas":{"WebhookSigningSecretInfo":{"type":"object","description":"A signing secret on a subscription, described without its value. Secrets are\nstored encrypted and are only ever shown once, when issued.","properties":{"id":{"type":"string","description":"Identifier for the secret. Not itself a secret."},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"When this secret stops verifying. `null` for the current secret, which does\nnot expire; a date on a secret being rotated away from."},"active":{"type":"boolean","description":"Whether the secret is still used to sign deliveries."}}}}},"paths":{"/partner/{partnerRegNo}/webhook/{webhookId}/secret":{"get":{"tags":["Webhook API"],"summary":"Get Webhook Signing Secrets","description":"An API to fetch (GET) which signing secrets exist on your Partner account's webhook\nsubscription and when each stops verifying.\n\nThis endpoint returns ids and dates only, never a secret value.\n\nA secret is shown once, in the response that issues it: the `PUT /partner/{partnerRegNo}/webhook/configure`\nthat creates the subscription, or `POST /partner/{partnerRegNo}/webhook/{webhookId}/secret`. It is stored\nencrypted and cannot be read back afterwards — if you have lost one, issue a new\none with `POST`.\n\n### Partner or Partners Account\nPartners can configure their own web hooks through this endpoint, or their\nchild accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.","operationId":"partner/get-webhook-secret","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/webhookId"}],"responses":{"200":{"$ref":"#/components/responses/WebhookSecretFetched"},"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Issue or Rotate Webhook Signing Secret > Issue a signing secret for your Partner account's webhook subscription, or rotate\ > an existing one. The same endpoint does both, and the plaintext secret is returned\ > here and nowhere else.\ > \ > \### Partner or Partners Account\ > Partners can configure their own web hooks through this endpoint, or their\ > child accounts using \`/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...\`.\ > \ > \`{webhookId}\` must match the \`id\` returned by \`PUT /partner/{partnerRegNo}/webhook/configure\`.\ > \ > Deliveries are then signed with HMAC-SHA256, so your endpoint can confirm the body\ > came from Qvalia unaltered. This is independent of the outbound credential under\ > \`.../auth\`, which authenticates Qvalia to your endpoint; use both. The secret is\ > symmetric — there is no public key to fetch — so treat it like a password.\ > \ > \### Verifying a delivery\ > \ > A signed delivery carries:\ > \ > \`\`\`\ > X-Qvalia-Event-Id: 4d1c9f84-3a2b-5c6d-9e0f-1a2b3c4d5e6f\ > X-Qvalia-Signature: t=1757846400,v1=5257a869e7ecebeda32affa62cdca3fa...\ > \`\`\`\ > \ > 1\. Parse \`t\` and every \`v1=\` value from \`X-Qvalia-Signature\`, ignoring prefixes you\ > do not recognise.\ > 2\. Reject the delivery if \`|now - t|\` exceeds your tolerance. 5 minutes is\ > recommended.\ > 3\. Compute \`HMAC-SHA256(secret, "\.\")\` and hex-encode it.\ > 4\. Compare against each \`v1=\` value in constant time. One match is enough.\ > 5\. Reject the delivery if you have already processed its \`X-Qvalia-Event-Id\`.\ > \ > Sign the exact bytes you received, not a re-serialised JSON object — key order and\ > whitespace change the hash. This is the most common cause of a failing first\ > implementation.\ > \ > Steps 2 and 5 are both needed: the timestamp caps how long a captured delivery\ > stays usable, and the event-id check is what rejects a replay inside that window.\ > The signature itself proves only origin and integrity.\ > \ > \### Rotation\ > \ > Calling this endpoint again issues a new secret and expires the previous ones\ > \`overlapHours\` (default 24) from now. While the window is open each delivery carries\ > a \`v1=\` part per active secret, so you can deploy the new one at your own pace. Use\ > \`overlapHours: 0\` if a secret has leaked. A subscription holds at most 5 secrets.\ > \ > Subscriptions created before signing existed carry no secret and stay unsigned until\ > you call this endpoint. ````json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner 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\""}},"requestBodies":{"WebhookSecretRotate":{"description":"Request body. Optional — omit it entirely to accept the default 24-hour overlap.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"overlapHours":{"type":"integer","minimum":0,"maximum":168,"default":24,"description":"How long the secrets being replaced keep verifying, so you can deploy\nthe new one at your own pace. During the window every delivery carries\na `v1=` part for each active secret.\n\nUse `0` when a secret has leaked: the old one stops verifying at once."}}}}}}},"responses":{"WebhookSecretIssued":{"description":"OK — the new signing secret. This is the only response that contains it.","content":{"application/json":{"schema":{"type":"object","properties":{"webhookId":{"type":"string","format":"uuid"},"algorithm":{"type":"string","enum":["hmac-sha256"]},"secretId":{"type":"string","description":"Identifier for the new secret. Not itself a secret."},"secret":{"type":"string","description":"The new signing secret, in clear text. **Store it now** — it is not\nretrievable afterwards. Rotate again if you lose it."},"createdAt":{"type":"string","format":"date-time"},"previousSecrets":{"type":"array","description":"Secrets this rotation replaced and when each stops verifying. Empty when\nthe subscription had no signing secret before.","items":{"type":"object","properties":{"id":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}}}}}},"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":{"/partner/{partnerRegNo}/webhook/{webhookId}/secret":{"post":{"tags":["Webhook API"],"summary":"Issue or Rotate Webhook Signing Secret","description":"Issue a signing secret for your Partner account's webhook subscription, or rotate\nan existing one. The same endpoint does both, and the plaintext secret is returned\nhere and nowhere else.\n\n### Partner or Partners Account\nPartners can configure their own web hooks through this endpoint, or their\nchild accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.\n\n`{webhookId}` must match the `id` returned by `PUT /partner/{partnerRegNo}/webhook/configure`.\n\nDeliveries are then signed with HMAC-SHA256, so your endpoint can confirm the body\ncame from Qvalia unaltered. This is independent of the outbound credential under\n`.../auth`, which authenticates Qvalia to your endpoint; use both. The secret is\nsymmetric — there is no public key to fetch — so treat it like a password.\n\n### Verifying a delivery\n\nA signed delivery carries:\n\n```\nX-Qvalia-Event-Id: 4d1c9f84-3a2b-5c6d-9e0f-1a2b3c4d5e6f\nX-Qvalia-Signature: t=1757846400,v1=5257a869e7ecebeda32affa62cdca3fa...\n```\n\n1. Parse `t` and every `v1=` value from `X-Qvalia-Signature`, ignoring prefixes you\n do not recognise.\n2. Reject the delivery if `|now - t|` exceeds your tolerance. 5 minutes is\n recommended.\n3. Compute `HMAC-SHA256(secret, \".\")` and hex-encode it.\n4. Compare against each `v1=` value in constant time. One match is enough.\n5. Reject the delivery if you have already processed its `X-Qvalia-Event-Id`.\n\nSign the exact bytes you received, not a re-serialised JSON object — key order and\nwhitespace change the hash. This is the most common cause of a failing first\nimplementation.\n\nSteps 2 and 5 are both needed: the timestamp caps how long a captured delivery\nstays usable, and the event-id check is what rejects a replay inside that window.\nThe signature itself proves only origin and integrity.\n\n### Rotation\n\nCalling this endpoint again issues a new secret and expires the previous ones\n`overlapHours` (default 24) from now. While the window is open each delivery carries\na `v1=` part per active secret, so you can deploy the new one at your own pace. Use\n`overlapHours: 0` if a secret has leaked. A subscription holds at most 5 secrets.\n\nSubscriptions created before signing existed carry no secret and stay unsigned until\nyou call this endpoint.","operationId":"partner/post-webhook-secret","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/webhookId"}],"requestBody":{"$ref":"#/components/requestBodies/WebhookSecretRotate"},"responses":{"200":{"$ref":"#/components/responses/WebhookSecretIssued"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ```` ## Delete Webhook Signing Secret > An API to DELETE signing from your Partner account's webhook subscription. Every secret is\ > removed and deliveries are sent \*\*unsigned\*\* from the next event onwards. The\ > subscription itself, and any outbound authentication on it, are kept.\ > \ > \### Partner or Partners Account\ > Partners can configure their own web hooks through this endpoint, or their\ > child accounts using \`/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...\`. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner 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":{"/partner/{partnerRegNo}/webhook/{webhookId}/secret":{"delete":{"tags":["Webhook API"],"summary":"Delete Webhook Signing Secret","description":"An API to DELETE signing from your Partner account's webhook subscription. Every secret is\nremoved and deliveries are sent **unsigned** from the next event onwards. The\nsubscription itself, and any outbound authentication on it, are kept.\n\n### Partner or Partners Account\nPartners can configure their own web hooks through this endpoint, or their\nchild accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.","operationId":"partner/delete-webhook-secret","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/webhookId"}],"responses":{"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Get Webhook Signing Secrets > An API to fetch (GET) which signing secrets exist on your child account webhook\ > subscription and when each stops verifying.\ > \ > This endpoint returns ids and dates only, never a secret value.\ > \ > A secret is shown once, in the response that issues it: the \`PUT /partner/{partnerRegNo}/account/{accountRegNo}/webhook/configure\`\ > that creates the subscription, or \`POST /partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/secret\`. It is stored\ > encrypted and cannot be read back afterwards — if you have lost one, issue a new\ > one with \`POST\`.\ > \ > \### Partner or Partners Account\ > Partners can configure their own web hooks through this endpoint, or their\ > child accounts using \`/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...\`. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner registration number issued by Qvalia"},"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":{"WebhookSecretFetched":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"webhookId":{"type":"string","format":"uuid"},"algorithm":{"type":"string","enum":["hmac-sha256"]},"secrets":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSigningSecretInfo"}}}}}}},"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"}}}}}}},"schemas":{"WebhookSigningSecretInfo":{"type":"object","description":"A signing secret on a subscription, described without its value. Secrets are\nstored encrypted and are only ever shown once, when issued.","properties":{"id":{"type":"string","description":"Identifier for the secret. Not itself a secret."},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","nullable":true,"description":"When this secret stops verifying. `null` for the current secret, which does\nnot expire; a date on a secret being rotated away from."},"active":{"type":"boolean","description":"Whether the secret is still used to sign deliveries."}}}}},"paths":{"/partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/secret":{"get":{"tags":["Webhook API"],"summary":"Get Webhook Signing Secrets","description":"An API to fetch (GET) which signing secrets exist on your child account webhook\nsubscription and when each stops verifying.\n\nThis endpoint returns ids and dates only, never a secret value.\n\nA secret is shown once, in the response that issues it: the `PUT /partner/{partnerRegNo}/account/{accountRegNo}/webhook/configure`\nthat creates the subscription, or `POST /partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/secret`. It is stored\nencrypted and cannot be read back afterwards — if you have lost one, issue a new\none with `POST`.\n\n### Partner or Partners Account\nPartners can configure their own web hooks through this endpoint, or their\nchild accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.","operationId":"partner/get-webhook-account-secret","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/accountRegNo"},{"$ref":"#/components/parameters/webhookId"}],"responses":{"200":{"$ref":"#/components/responses/WebhookSecretFetched"},"204":{"$ref":"#/components/responses/NoContent"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Issue or Rotate Webhook Signing Secret > Issue a signing secret for a child account's webhook subscription, or rotate an existing one.\ > The same endpoint does both, and the plaintext secret is returned here and nowhere\ > else.\ > \ > \`{webhookId}\` must match the \`id\` returned by \`PUT /partner/{partnerRegNo}/account/{accountRegNo}/webhook/configure\`.\ > \ > Deliveries are then signed with HMAC-SHA256 (\`X-Qvalia-Signature\`). See\ > \`POST /partner/{partnerRegNo}/webhook/{webhookId}/secret\` for how to verify a\ > delivery, the rotation rules and the \`overlapHours\` window. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner registration number issued by Qvalia"},"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\""}},"requestBodies":{"WebhookSecretRotate":{"description":"Request body. Optional — omit it entirely to accept the default 24-hour overlap.","required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"overlapHours":{"type":"integer","minimum":0,"maximum":168,"default":24,"description":"How long the secrets being replaced keep verifying, so you can deploy\nthe new one at your own pace. During the window every delivery carries\na `v1=` part for each active secret.\n\nUse `0` when a secret has leaked: the old one stops verifying at once."}}}}}}},"responses":{"WebhookSecretIssued":{"description":"OK — the new signing secret. This is the only response that contains it.","content":{"application/json":{"schema":{"type":"object","properties":{"webhookId":{"type":"string","format":"uuid"},"algorithm":{"type":"string","enum":["hmac-sha256"]},"secretId":{"type":"string","description":"Identifier for the new secret. Not itself a secret."},"secret":{"type":"string","description":"The new signing secret, in clear text. **Store it now** — it is not\nretrievable afterwards. Rotate again if you lose it."},"createdAt":{"type":"string","format":"date-time"},"previousSecrets":{"type":"array","description":"Secrets this rotation replaced and when each stops verifying. Empty when\nthe subscription had no signing secret before.","items":{"type":"object","properties":{"id":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}}}}}}}},"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":{"/partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/secret":{"post":{"tags":["Webhook API"],"summary":"Issue or Rotate Webhook Signing Secret","description":"Issue a signing secret for a child account's webhook subscription, or rotate an existing one.\nThe same endpoint does both, and the plaintext secret is returned here and nowhere\nelse.\n\n`{webhookId}` must match the `id` returned by `PUT /partner/{partnerRegNo}/account/{accountRegNo}/webhook/configure`.\n\nDeliveries are then signed with HMAC-SHA256 (`X-Qvalia-Signature`). See\n`POST /partner/{partnerRegNo}/webhook/{webhookId}/secret` for how to verify a\ndelivery, the rotation rules and the `overlapHours` window.","operationId":"partner/post-webhook-account-secret","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$ref":"#/components/parameters/accountRegNo"},{"$ref":"#/components/parameters/webhookId"}],"requestBody":{"$ref":"#/components/requestBodies/WebhookSecretRotate"},"responses":{"200":{"$ref":"#/components/responses/WebhookSecretIssued"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ## Delete Webhook Signing Secret > An API to DELETE signing from your child account webhook subscription. Every secret is\ > removed and deliveries are sent \*\*unsigned\*\* from the next event onwards. The\ > subscription itself, and any outbound authentication on it, are kept.\ > \ > \### Partner or Partners Account\ > Partners can configure their own web hooks through this endpoint, or their\ > child accounts using \`/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...\`. ```json {"openapi":"3.0.2","info":{"title":"Qvalia Partner API","version":"1.0.0"},"tags":[{"name":"Webhook API","description":"Operations related to Web hooks"}],"servers":[{"url":"https://api-test.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 \n\nObtain a token via POST /token/{accountRegNo} (see Authentication API).\n"}},"parameters":{"partnerRegNo":{"name":"partnerRegNo","in":"path","required":true,"schema":{"type":"string"},"description":"Partner registration number issued by Qvalia"},"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":{"/partner/{partnerRegNo}/account/{accountRegNo}/webhook/{webhookId}/secret":{"delete":{"tags":["Webhook API"],"summary":"Delete Webhook Signing Secret","description":"An API to DELETE signing from your child account webhook subscription. Every secret is\nremoved and deliveries are sent **unsigned** from the next event onwards. The\nsubscription itself, and any outbound authentication on it, are kept.\n\n### Partner or Partners Account\nPartners can configure their own web hooks through this endpoint, or their\nchild accounts using `/partner/{partnerRegNo}/account/{accountRegNo}/webhook/...`.","operationId":"partner/delete-webhook-account-secret","parameters":[{"$ref":"#/components/parameters/partnerRegNo"},{"$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/partner-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.