Skip to main content

Integrations & Webhooks

Node.js

Use the Purgit API from any Node.js application with the built-in fetch API (Node 18+):

import fs from 'node:fs';
import path from 'node:path';

const PURGIT_API_KEY = process.env.PURGIT_API_KEY;
const BASE_URL = 'https://api.purgit.io/v1';

async function scanFile(filePath) {
  const fileBuffer = await fs.promises.readFile(filePath);
  const form = new FormData();
  form.append('file', new Blob([fileBuffer]), path.basename(filePath));
  form.append('policy', 'standard');

  const response = await fetch(`${BASE_URL}/scan`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${PURGIT_API_KEY}` },
    body: form,
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Scan failed: ${error.code} — ${error.error}`);
  }

  return response.json();
}

// Usage
const report = await scanFile('./contract.pdf');
console.log(`Found ${report.data.summary.totalFindings} findings`);

Sanitize and Save

async function sanitizeFile(filePath, outputPath) {
  const fileBuffer = await fs.promises.readFile(filePath);
  const form = new FormData();
  form.append('file', new Blob([fileBuffer]), path.basename(filePath));
  form.append('policy', 'standard');

  const response = await fetch(`${BASE_URL}/sanitize`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${PURGIT_API_KEY}` },
    body: form,
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Sanitize failed: ${error.code} — ${error.error}`);
  }

  const cleanFile = Buffer.from(await response.arrayBuffer());
  await fs.promises.writeFile(outputPath, cleanFile);

  const reportId = response.headers.get('X-Purgit-Report-Id');
  console.log(`Sanitized file saved. Report: ${reportId}`);
}

Python

Use the requests library for straightforward integration:

import os
import requests

PURGIT_API_KEY = os.environ['PURGIT_API_KEY']
BASE_URL = 'https://api.purgit.io/v1'


def scan_file(file_path: str, policy: str = 'standard') -> dict:
    """Scan a file and return the report as a dictionary."""
    with open(file_path, 'rb') as f:
        response = requests.post(
            f'{BASE_URL}/scan',
            headers={'Authorization': f'Bearer {PURGIT_API_KEY}'},
            files={'file': f},
            data={'policy': policy},
        )
    response.raise_for_status()
    return response.json()


def sanitize_file(file_path: str, output_path: str, policy: str = 'standard'):
    """Sanitize a file and save the clean version."""
    with open(file_path, 'rb') as f:
        response = requests.post(
            f'{BASE_URL}/sanitize',
            headers={'Authorization': f'Bearer {PURGIT_API_KEY}'},
            files={'file': f},
            data={'policy': policy},
        )
    response.raise_for_status()

    with open(output_path, 'wb') as out:
        out.write(response.content)

    report_id = response.headers.get('X-Purgit-Report-Id')
    print(f'Sanitized file saved to {output_path}. Report: {report_id}')


# Usage
report = scan_file('contract.pdf', policy='legal')
print(f"Found {report['data']['summary']['totalFindings']} findings")

sanitize_file('contract.pdf', 'contract-clean.pdf', policy='legal')

GitHub Actions

Add automated document scanning to your CI/CD pipeline. This workflow scans all documents in docs/ and contracts/ directories when a pull request touches them:

name: Scan documents before merge
on:
  pull_request:
    paths:
      - 'docs/**'
      - 'contracts/**'
      - '**.pdf'
      - '**.docx'

jobs:
  scan-documents:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Purgit CLI
        run: npm install -g purgit-cli

      - name: Authenticate
        env:
          PURGIT_API_KEY: ${{ secrets.PURGIT_API_KEY }}
        run: echo "Using API key authentication"

      - name: Scan changed documents
        env:
          PURGIT_API_KEY: ${{ secrets.PURGIT_API_KEY }}
        run: |
          # Find all PDF and DOCX files changed in this PR
          CHANGED_FILES=$(git diff --name-only origin/main...HEAD | grep -E '\.(pdf|docx|jpg|jpeg|png)$' || true)

          if [ -z "$CHANGED_FILES" ]; then
            echo "No document files changed."
            exit 0
          fi

          FAILED=0
          for file in $CHANGED_FILES; do
            echo "Scanning: $file"
            purgit scan "$file" --policy standard --format json --output "report-$(basename $file).json" --quiet
            STATUS=$?
            if [ $STATUS -eq 1 ]; then
              echo "  Findings detected in $file"
              FAILED=1
            elif [ $STATUS -ge 2 ]; then
              echo "  Error scanning $file (exit code: $STATUS)"
            fi
          done

          if [ $FAILED -eq 1 ]; then
            echo ""
            echo "One or more documents have metadata findings."
            echo "Run 'purgit sanitize <file>' locally to clean them."
            exit 1
          fi

      - name: Upload scan reports
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: purgit-scan-reports
          path: report-*.json

Block Releases with Critical Findings

For stricter enforcement, check severity levels:

- name: Check for critical findings
  run: |
    for report in report-*.json; do
      CRITICAL=$(jq '.data.summary.bySeverity.critical' "$report")
      if [ "$CRITICAL" -gt 0 ]; then
        echo "CRITICAL findings in $report — blocking release."
        jq '.data.findings[] | select(.severity == "critical")' "$report"
        exit 1
      fi
    done

Webhooks

Configure webhooks to receive notifications when scans complete. Set up webhook URLs in your dashboard under Settings > Webhooks.

Webhook Payload

When a scan completes, Purgit sends a POST request to your webhook URL with the following payload:

{
  "event": "scan.completed",
  "timestamp": "2026-03-06T14:23:14Z",
  "data": {
    "reportId": "rpt_01HX7K9M...",
    "file": {
      "name": "contract.pdf",
      "format": "pdf",
      "hash": "sha256:a1b2c3d4..."
    },
    "summary": {
      "totalFindings": 5,
      "bySeverity": {
        "critical": 0,
        "high": 2,
        "medium": 2,
        "low": 1,
        "info": 0
      }
    },
    "policy": "legal"
  }
}

Webhook Headers

Content-Type: application/json
X-Purgit-Signature: sha256=<HMAC signature>
X-Purgit-Event: scan.completed
X-Purgit-Delivery: dlv_01HX...

Verifying Webhook Signatures

Verify the X-Purgit-Signature header to ensure the webhook came from Purgit:

import crypto from 'node:crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

Webhook Events

| Event | Description | |-------|-------------| | scan.completed | A scan has finished processing | | sanitize.completed | A file has been sanitized and verified | | scan.failed | A scan encountered an error |

n8n / Zapier / Make

Use the REST API directly via HTTP request nodes in your automation platform:

  1. Trigger: File uploaded to Google Drive / Dropbox / S3.
  2. HTTP Request: POST to https://api.purgit.io/v1/scan with the file.
  3. Condition: Check summary.totalFindings > 0.
  4. Action: If findings exist, POST to /v1/sanitize and save the clean file back.
  5. Notification: Send a Slack/email notification with the scan summary.

Set the Authorization header to Bearer <your API key> on all HTTP request nodes.

Next Steps

Last updated: 2026-03-06