Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/juescoryisus/QualityDocD/llms.txt

Use this file to discover all available pages before exploring further.

The webhook endpoint allows external systems to push document approval events into QualityDocD’s Node.js API. When an approval occurs in an upstream service — a DMS, an e-signature platform, or a CI pipeline — that service can POST a structured payload to this endpoint so QualityDocD can react accordingly. The endpoint validates every incoming payload with a Zod schema and logs the event using the application’s pino logger.

​
POST /webhooks/document-approved

Receives a document approval event from an external service. The request body is validated synchronously; if validation passes the event is logged and { received: true } is returned immediately. Authentication: None required. This is an open endpoint intended for trusted internal services.
Because this endpoint has no authentication, it must be protected at the network level in production. Use an IP allowlist, a private VPC, or an HMAC signature verification layer to ensure only authorised services can deliver events. See the Securing webhooks section below.

​
Request headers

​
Content-Type
string
required
Must be application/json.

​
Request body

The body is validated against the ReceiveDocumentApprovedEventBody Zod schema. All four fields are required.
​
documentId
number
required
Numeric ID of the document that was approved. Must match an existing document record in QualityDocD.
​
versionId
number
required
Numeric ID of the specific document version that was approved.
​
companyId
number
required
Numeric ID of the company tenant the document belongs to.
​
approvedAt
string
required
ISO 8601 datetime string indicating when the approval occurred in the external system (e.g. "2025-01-15T14:30:00Z").

​
Response — 200 OK

​
received
boolean
Always true when the payload passes validation and the event is logged successfully.

​
Error responses

StatusMeaning
400 Bad RequestThe request body failed Zod validation — one or more required fields are missing or have the wrong type. The response body includes a "error" string with the Zod message.

​
Example

curl -X POST http://localhost:5000/webhooks/document-approved \
  -H "Content-Type: application/json" \
  -d '{"documentId":42,"versionId":7,"companyId":1,"approvedAt":"2025-01-15T14:30:00Z"}'

​
What happens after the event is received

Currently, a successfully validated event is logged only — no database write or downstream action is triggered automatically. The pino logger records the full payload at the info level: 
{"level":30,"documentId":42,"versionId":7,"companyId":1,"approvedAt":"2025-01-15T14:30:00Z","msg":"Received document-approved event from external service"}
To trigger downstream actions — such as updating the document version’s status to current, sending a notification, or reindexing the document in the search service — extend the handler in src/routes/webhooks.ts after the logger.info(...) call. The parsed and validated data is already available via destructuring: { documentId, versionId, companyId, approvedAt }.

​
Securing webhooks in production

Because the endpoint requires no authentication, it should never be exposed on a public interface without additional protection. Recommended approaches:
  • IP allowlist — Configure your reverse proxy or firewall to allow POST /webhooks/* only from known source IP ranges of trusted services.
  • Private network — Place QualityDocD’s Node.js API in a private VPC or internal network segment that external traffic cannot reach directly.
  • HMAC signature verification — Have the sending service attach an X-Signature header (HMAC-SHA256 of the raw body using a shared secret) and verify it in middleware before the route handler runs.
  • mTLS — For high-security environments, require mutual TLS between the sending service and the API server.

​
GET /healthz

Returns the service health status. Used by Docker Compose health checks and uptime monitors. No authentication required. Authentication: None.

​
Response — 200 OK

​
status
string
Always "ok" when the service is running and able to handle requests.

​
Example

curl http://localhost:5000/healthz

Build docs developers (and LLMs) love

Get started for freeTalk to us