{
  "openapi": "3.0.0",
  "info": {
    "title": "Probatix Webhooks v1",
    "description": "This specification documents outgoing webhooks sent by Probatix.\n\nWebhook payload models are the same models used by the Probatix Diagnostics API v1 and Specimen Collection Kit API v1.\n\nEach delivery includes a base64-encoded HMAC-SHA256 signature of the raw request body\nin the `X-Probatix-Hmac-SHA256` header.\nCalculate the signature with your webhook signing secret and compare it in constant time before processing the payload.",
    "version": "1.28.0"
  },
  "servers": [
    {
      "url": "https://api.sandbox.probatix.de/",
      "description": "Sandbox environment for E2E testing."
    },
    {
      "url": "https://api.probatix.de/",
      "description": "Production environment."
    }
  ],
  "paths": [],
  "components": {
    "schemas": {
      "RangeInterval": {
        "type": "object",
        "required": [
          "label"
        ],
        "properties": {
          "label": {
            "description": "Optional human-readable label for the interval, for example `negative` or `positive`.",
            "example": "negative",
            "type": "string"
          },
          "lower": {
            "description": "Optional lower boundary of the interval. Lower boundaries use `>` or `>=` operators.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/Boundary"
              }
            ],
            "nullable": true
          },
          "upper": {
            "description": "Optional upper boundary of the interval. Upper boundaries use `<` or `<=` operators.",
            "example": {
              "operator": "<=",
              "value": 5.5
            },
            "anyOf": [
              {
                "$ref": "#/components/schemas/Boundary"
              }
            ],
            "nullable": true
          }
        }
      },
      "Boundary": {
        "type": "object",
        "required": [
          "operator"
        ],
        "properties": {
          "operator": {
            "description": "Comparison operator for the boundary. Lower boundaries use `>` or `>=`; upper boundaries use `<` or `<=`.",
            "example": "<=",
            "type": "string",
            "enum": [
              ">",
              ">=",
              "<",
              "<="
            ]
          },
          "value": {
            "description": "Boundary value used together with the operator.",
            "example": 5.5,
            "type": "number",
            "nullable": true
          }
        }
      },
      "DiagnosticOrder": {
        "type": "object",
        "required": [
          "id",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "diagnosticTests": {
            "description": "IRIs of the diagnostic tests that belong to this order.",
            "example": [
              "/v1/diagnostic_tests/00112233-4455-6677-8899-aabbccddeeff"
            ],
            "type": "array",
            "items": {
              "type": "string",
              "format": "iri-reference"
            }
          },
          "createdAt": {
            "description": "Timestamp when the order was created.",
            "type": "string",
            "format": "date-time"
          },
          "fulfilledAt": {
            "description": "Timestamp when the outbound shipment was handed over.",
            "example": "2026-05-04T09:15:00+00:00",
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "shipmentTracking": {
            "description": "Tracking details for the outbound shipment, when available.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/ShipmentTracking"
              }
            ],
            "nullable": true
          },
          "shippingAddress": {
            "description": "Shipping address stored for the order.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/FullAddressInput"
              }
            ],
            "nullable": true
          },
          "metadata": {
            "description": "Optional partner-defined metadata. Up to 10 entries are supported and values must be JSON primitive values (string, number, or boolean).",
            "example": {
              "yourReference1": "abc",
              "yourReference2": 123,
              "yourFlag1": true
            },
            "type": "object",
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "number"
                },
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "nullable": true
          }
        }
      },
      "ShipmentTracking": {
        "type": "object",
        "required": [
          "provider",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "provider": {
            "example": "DHL",
            "type": "string",
            "enum": [
              "DHL",
              "Swiss Post",
              "OTHER"
            ]
          },
          "createdAt": {
            "description": "Timestamp when the shipment was created.",
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "description": "Timestamp when the shipment was last updated.",
            "type": "string",
            "format": "date-time"
          },
          "trackingCode": {
            "example": "123",
            "type": "string",
            "nullable": true
          },
          "url": {
            "example": "https://www.dhl.de/en/privatkunden/dhl-sendungsverfolgung.html?piececode=123",
            "type": "string",
            "format": "url"
          },
          "shipmentStatus": {
            "description": "Normalized shipment status for informational purposes only.",
            "example": {
              "terminalStatus": true,
              "name": "DELIVERED",
              "value": "delivered"
            },
            "type": "string",
            "enum": [
              "confirmed",
              "in_transit",
              "out_for_delivery",
              "delivered",
              "failure",
              "undeliverable",
              "returned_to_sender",
              "available_for_collection",
              null
            ],
            "nullable": true
          },
          "providerStatus": {
            "description": "Shipment status from the provider please note some Providers are not 100% reliable and will occasionally deliver shipments without status updates.",
            "example": {
              "terminalStatus": true,
              "name": "DELIVERED",
              "value": "delivered"
            },
            "type": "string",
            "nullable": true
          },
          "rawProviderHistory": {
            "description": "Raw shipment history from the provider.",
            "type": "array",
            "items": {},
            "nullable": true
          }
        }
      },
      "FullAddressInput": {
        "type": "object",
        "required": [
          "address1",
          "zip",
          "city",
          "firstName",
          "lastName"
        ],
        "properties": {
          "address1": {
            "example": "Bismarckstraße 10-12",
            "type": "string"
          },
          "address2": {
            "example": "6. OG",
            "type": "string",
            "nullable": true
          },
          "zip": {
            "example": "10625",
            "type": "string"
          },
          "city": {
            "example": "Berlin",
            "type": "string"
          },
          "countryCode": {
            "default": "DE",
            "example": "DE",
            "type": "string"
          },
          "firstName": {
            "example": "Jane",
            "type": "string"
          },
          "lastName": {
            "example": "Doe",
            "type": "string"
          },
          "id": {
            "readOnly": true,
            "type": "string",
            "format": "uuid"
          },
          "phone": {
            "example": "030 12345678",
            "type": "string",
            "nullable": true
          },
          "company": {
            "example": "Probatix Health GmbH",
            "type": "string",
            "nullable": true
          },
          "name": {
            "example": "Probatix Health GmbH",
            "type": "string",
            "nullable": true
          }
        }
      },
      "DiagnosticTest": {
        "type": "object",
        "required": [
          "id",
          "diagnosticOrder",
          "diagnosticProduct",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "diagnosticOrder": {
            "description": "IRI of the parent diagnostic order.",
            "example": "/v1/diagnostic_orders/00112233-4455-6677-8899-aabbccddeeff",
            "type": "string",
            "format": "iri-reference"
          },
          "diagnosticProduct": {
            "description": "IRI of the DiagnosticProduct that was ordered for this test.",
            "example": "/v1/diagnostic_products/00112233-4455-6677-8899-aabbccddeeff",
            "type": "string",
            "format": "iri-reference"
          },
          "testResults": {
            "description": "IRIs of linked test results, sorted by `createdAt`. In most patient-facing use cases, the most recent test result is the relevant one. Older results are included for transparency and historical records.",
            "example": [
              "/v1/test_results/00112233-4455-6677-8899-aabbccddeeff"
            ],
            "type": "array",
            "items": {
              "type": "string",
              "format": "iri-reference"
            }
          },
          "patient": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Patient"
              }
            ],
            "nullable": true
          },
          "specimens": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Specimen"
            }
          },
          "shipmentTracking": {
            "description": "Tracking details for the patient-to-lab shipment when available.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/ShipmentTracking"
              }
            ],
            "nullable": true
          },
          "activatedAt": {
            "description": "Timestamp when the patient activated the TestKit.",
            "example": "2026-05-04T10:30:00+00:00",
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "labIntakeAt": {
            "description": "Timestamp when the specimen arrived in the laboratory.",
            "example": "2026-05-06T07:45:00+00:00",
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "replacementDiagnosticTest": {
            "description": "IRI of the diagnostic test that replaced this test, when it was replaced.",
            "example": "/v1/diagnostic_tests/00112233-4455-6677-8899-aabbccddeeff",
            "type": "string",
            "format": "iri-reference"
          },
          "replacesDiagnosticTest": {
            "description": "IRI of the diagnostic test this test replaces, when applicable.",
            "example": "/v1/diagnostic_tests/00112233-4455-6677-8899-aabbccddeeff",
            "type": "string",
            "format": "iri-reference"
          },
          "canceledAt": {
            "description": "Timestamp when the diagnostic test was canceled.",
            "example": "2026-05-04T10:30:00+00:00",
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "completedAt": {
            "description": "Timestamp when the diagnostic test was completed.",
            "example": "2026-05-06T07:45:00+00:00",
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "fulfilledAt": {
            "description": "Timestamp when fulfillment of the diagnostic test was completed.",
            "example": "2026-05-06T07:45:00+00:00",
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "createdAt": {
            "description": "Timestamp when the DiagnosticTest was created.",
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Patient": {
        "type": "object",
        "properties": {
          "email": {
            "example": "noreply@probatix.de",
            "type": "string",
            "format": "email"
          },
          "firstName": {
            "example": "Jane",
            "type": "string",
            "nullable": true
          },
          "lastName": {
            "example": "Doe",
            "type": "string",
            "nullable": true
          },
          "gender": {
            "default": "X",
            "type": "string",
            "enum": [
              "M",
              "F",
              "D",
              "X"
            ]
          },
          "dateOfBirth": {
            "example": "1994-01-15",
            "type": "string",
            "format": "date"
          },
          "healthInsuranceDetails": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/HealthInsuranceDetails"
              }
            ],
            "nullable": true
          }
        }
      },
      "HealthInsuranceDetails": {
        "type": "object",
        "properties": {
          "countryCode": {
            "example": "DE",
            "type": "string",
            "nullable": true
          },
          "provider": {
            "example": "Example Insurance",
            "type": "string",
            "nullable": true
          },
          "healthInsuranceTypeDE": {
            "example": "GKV",
            "type": "string",
            "enum": [
              "GKV",
              "PKV",
              null
            ],
            "nullable": true
          },
          "subscriberIdentifier": {
            "description": "The insurer assigned ID for the Subscriber.",
            "type": "string",
            "nullable": true
          }
        }
      },
      "Specimen": {
        "type": "object",
        "required": [
          "specimenCode",
          "createdAt"
        ],
        "properties": {
          "specimenCode": {
            "description": "Laboratory specimen code or sample identifier.",
            "example": "ABC-123456",
            "type": "string"
          },
          "createdAt": {
            "description": "Timestamp when the specimen record was created.",
            "type": "string",
            "format": "date-time"
          },
          "collectionDate": {
            "description": "Date when the specimen was collected.",
            "example": "2026-05-04",
            "type": "string",
            "format": "date"
          },
          "collectionTime": {
            "description": "Time of day when the specimen was collected.",
            "example": "13:50:00",
            "type": "string",
            "pattern": "^\\d{2}:\\d{2}:\\d{2}$"
          },
          "menstrualPhaseAtCollection": {
            "description": "Menstrual phase reported at collection time, when applicable.",
            "type": "string",
            "enum": [
              "follikel",
              "ovulation",
              "luteal",
              "menopause",
              null
            ],
            "nullable": true
          }
        }
      },
      "TestResult": {
        "type": "object",
        "required": [
          "id",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "createdAt": {
            "description": "Timestamp when the test result was created.",
            "type": "string",
            "format": "date-time"
          },
          "observations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Observation"
            }
          },
          "documents": {
            "description": "Embedded document metadata objects, such as PDF reports. Unlike most relations in this API, documents are included inline for convenience.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Document"
            }
          },
          "labNotes": {
            "description": "Free-text laboratory notes attached to the test result.",
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "diagnosticTest": {
            "type": "string"
          }
        }
      },
      "Observation": {
        "type": "object",
        "required": [
          "id",
          "testResult",
          "loincNum",
          "value",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "testResult": {
            "description": "IRI of the parent test result.",
            "example": "/v1/test_results/00112233-4455-6677-8899-aabbccddeeff",
            "type": "string",
            "format": "iri-reference"
          },
          "loincNum": {
            "description": "LOINC code of the reported analyte.",
            "example": "2570-0",
            "type": "string"
          },
          "value": {
            "description": "Raw value as reported by the laboratory. The API exposes it as a string to preserve the original representation. Clients should not assume the value is always safely parseable as a number.",
            "example": "5.5",
            "type": "string"
          },
          "unit": {
            "description": "Measurement unit when the laboratory provides one.",
            "example": "µg/g",
            "type": "string",
            "nullable": true
          },
          "referenceRange": {
            "description": "Reference range or interval information supplied for the observation. The structure is interval-based: each interval may define a `lower` and/or `upper` boundary with an operator such as `>`, `>=`, `<`, or `<=`, plus an optional human-readable label such as `negative` or `positive`.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/ObservationReferenceRange"
              }
            ],
            "nullable": true
          },
          "interpretation": {
            "description": "Laboratory interpretation, for example positive or negative.",
            "example": "negative",
            "type": "string",
            "nullable": true
          },
          "labNotes": {
            "description": "Free-text notes supplied alongside the observation.",
            "example": [
              "Kein Hinweis auf okkultes Blut im Stuhl."
            ],
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "createdAt": {
            "description": "Timestamp when the observation was created.",
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ObservationReferenceRange": {
        "type": "object",
        "required": [
          "intervals"
        ],
        "properties": {
          "intervals": {
            "description": "Reference intervals for the observation. Each interval may define a `lower` and/or `upper` boundary and can optionally provide a human-readable label such as `negative` or `positive`.",
            "example": [
              {
                "label": "negative",
                "lower": null,
                "upper": {
                  "operator": "<=",
                  "value": 5.5
                }
              },
              {
                "label": "positive",
                "lower": {
                  "operator": ">",
                  "value": 5.5
                },
                "upper": null
              }
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RangeInterval"
            }
          }
        }
      },
      "Document": {
        "type": "object",
        "required": [
          "id",
          "originalFileName",
          "downloadPath",
          "mimeType",
          "size"
        ],
        "properties": {
          "id": {
            "example": "00112233-4455-6677-8899-aabbccddeeff",
            "type": "string",
            "format": "uuid"
          },
          "originalFileName": {
            "example": "example.pdf",
            "type": "string"
          },
          "downloadPath": {
            "description": "Relative download path for the binary document.",
            "example": "/v1/documents/00112233-4455-6677-8899-aabbccddeeff/download",
            "type": "string",
            "format": "iri-reference"
          },
          "mimeType": {
            "example": "application/pdf",
            "type": "string"
          },
          "size": {
            "description": "Document size in bytes.",
            "example": 630,
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SpecimenCollectionKit": {
        "type": "object",
        "required": [
          "id",
          "product",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "product": {
            "description": "IRI of the specimen collection kit product this kit belongs to.",
            "example": "/sck/v1/products/00112233-4455-6677-8899-aabbccddeeff",
            "type": "string",
            "format": "iri-reference"
          },
          "fulfillmentData": {
            "description": "Optional fulfillment-specific data. Values must be JSON primitive values.",
            "example": {
              "barcode": "PX-123456789",
              "kitId": "KIT-2026-000123",
              "verified": true
            },
            "type": "object",
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "number"
                },
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "nullable": true
          },
          "udi": {
            "description": "Parsed unique device identifier details when a UDI is linked to this kit.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/UniqueDeviceIdentifierDetail"
              }
            ],
            "nullable": true
          },
          "createdAt": {
            "example": "2026-06-29T10:30:00+00:00",
            "type": "string",
            "format": "date-time"
          },
          "fulfilledAt": {
            "example": "2026-06-29T10:30:00+00:00",
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "outboundShipment": {
            "description": "Outbound shipment for this kit when its fulfillment bundle has been shipped.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/ShipmentTracking"
              }
            ],
            "nullable": true
          },
          "returnShipment": {
            "description": "Return shipment for this kit when its fulfillment bundle has one.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/ShipmentTracking"
              }
            ],
            "nullable": true
          },
          "replacesKit": {
            "description": "IRI of the SCK kit this kit replaces.",
            "type": "string",
            "nullable": true
          },
          "replacementKit": {
            "description": "IRI of the SCK kit that replaced this kit.",
            "type": "string",
            "nullable": true
          }
        }
      },
      "UniqueDeviceIdentifierDetail": {
        "type": "object",
        "required": [
          "normalizedText",
          "deviceIdentifier"
        ],
        "properties": {
          "normalizedText": {
            "example": "(01)05056751601985(10)PCCN000844(17)270831(240)KT90011",
            "type": "string"
          },
          "deviceIdentifier": {
            "example": "05056751601985",
            "type": "string"
          },
          "lotNumber": {
            "example": "PCCN000844",
            "type": "string",
            "nullable": true
          },
          "serialNumber": {
            "type": "string",
            "nullable": true
          },
          "additionalProductIdentifier": {
            "example": "KT90011",
            "type": "string",
            "nullable": true
          },
          "expirationDate": {
            "example": "2027-08-31",
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "manufactureDate": {
            "example": "2026-06-15",
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "SpecimenCollectionKitOrder": {
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kits": {
            "description": "IRIs of the specimen collection kits that belong to this order.",
            "example": [
              "/sck/v1/kits/00112233-4455-6677-8899-aabbccddeeff"
            ],
            "type": "array",
            "items": {
              "type": "string",
              "format": "iri-reference"
            }
          },
          "contact": {
            "$ref": "#/components/schemas/ShipmentContact"
          },
          "shippingAddress": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FullAddressInput"
              }
            ],
            "nullable": true
          },
          "metadata": {
            "description": "Optional partner-defined metadata. Values must be JSON primitive values.",
            "example": {
              "yourReference1": "abc",
              "yourReference2": 123,
              "priority": true
            },
            "type": "object",
            "additionalProperties": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "number"
                },
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "nullable": true
          },
          "status": {
            "description": "Current SCK order status.",
            "example": "new",
            "type": "string",
            "enum": [
              "new",
              "fulfilled",
              "canceled"
            ]
          },
          "createdAt": {
            "example": "2026-06-29T10:30:00+00:00",
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "fulfilledAt": {
            "example": "2026-06-30T09:15:00+00:00",
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "outboundShipment": {
            "description": "Outbound shipment for this kit when its fulfillment bundle has been shipped.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/ShipmentTracking"
              }
            ],
            "nullable": true
          },
          "returnShipment": {
            "description": "Return shipment for this kit when its fulfillment bundle has one.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/ShipmentTracking"
              }
            ],
            "nullable": true
          }
        }
      },
      "ShipmentContact": {
        "type": "object",
        "required": [
          "firstName",
          "lastName",
          "email"
        ],
        "properties": {
          "firstName": {
            "example": "Jane",
            "type": "string"
          },
          "lastName": {
            "example": "Doe",
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "noreply@probatix.de"
          },
          "phone": {
            "example": "030 12345678",
            "type": "string",
            "nullable": true
          }
        }
      }
    },
    "responses": {},
    "parameters": {},
    "examples": {},
    "requestBodies": {},
    "headers": {},
    "securitySchemes": {}
  },
  "security": [],
  "tags": []
}