Webhooks

Webhooks allow you to receive real-time updates about results (and soon statuses) from the Parcha API. This guide explains how to use webhooks, including how to set them up, secure them with HMAC signatures, and test them.

Setting Up Webhooks

Parcha API supports two types of webhooks:

Job Webhooks (webhook_url): Receive notifications when the entire job is completed
Tool Webhooks (tool_webhook_url): Receive real-time updates each time an LLM tool is executed during the job

You can specify either or both webhook URLs when initiating a job:

curl -X POST 'https://api.parcha.ai/api/v1/startKYBAgentJob' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "agent_key": "your-agent-key",
  "kyb_schema": {
    "id": "case-001",
    "self_attested_data": {
      "business_name": "Example Corp",
      "incorporation_documents": [
        {
          "url": "https://example.com/document.pdf",
          "type": "Document",
          "file_name": "incorporation.pdf"
        }
      ]
    }
  },
  "webhook_url": "https://your-webhook-url.com/job-callback",
  "tool_webhook_url": "https://your-webhook-url.com/tool-callback"
}'

import requests

api_key = 'YOUR_API_KEY'
url = 'https://api.parcha.ai/api/v1/startKYBAgentJob'

data = {
    "agent_key": "your-agent-key",
    "kyb_schema": {
        "id": "case-001",
        "self_attested_data": {
            "business_name": "Example Corp",
            "incorporation_documents": [
                {
                    "url": "https://example.com/document.pdf",
                    "type": "Document",
                    "file_name": "incorporation.pdf"
                }
            ]
        }
    },
    "webhook_url": "https://your-webhook-url.com/job-callback",
    "tool_webhook_url": "https://your-webhook-url.com/tool-callback"
}

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

import axios from 'axios';

const apiKey = 'YOUR_API_KEY';
const url = 'https://api.parcha.ai/api/v1/startKYBAgentJob';

const data = {
  agent_key: "your-agent-key",
  kyb_schema: {
    id: "case-001",
    self_attested_data: {
      business_name: "Example Corp",
      incorporation_documents: [
        {
          url: "https://example.com/document.pdf",
          type: "Document",
          file_name: "incorporation.pdf"
        }
      ]
    }
  },
  webhook_url: "https://your-webhook-url.com/job-callback",
  tool_webhook_url: "https://your-webhook-url.com/tool-callback"
};

axios.post(url, data, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
})
.then(response => console.log(response.data))
.catch(error => console.error('Error:', error));

Webhook Payloads

Job Webhook Payload

When a job is completed, Parcha API sends a POST request to your webhook URL with a payload containing job status information. Note: The webhook payload contains job status updates only, not the full check results.

{
  "id": "e85e0cc4-b1e8-40b0-9a3d-83c328eee0f4",
  "agent_id": "remediation-v1",
  "status": "complete",
  "recommendation": "Approve",
  "created_at": "2024-09-18T18:30:00.000000",
  "updated_at": "2024-09-18T18:31:05.094700",
  "input_payload": {
    "id": "case-001",
    "self_attested_data": {
      "business_name": "Example Corp"
    }
  }
}

Fetching Full Check Results

To get the complete check results after receiving a webhook notification, use the getJobById endpoint with include_check_results=true:

curl -X GET 'https://api.parcha.ai/api/v1/getJobById?job_id=e85e0cc4-b1e8-40b0-9a3d-83c328eee0f4&include_check_results=true' \
-H 'Authorization: Bearer YOUR_API_KEY'

Process webhook payloads quickly and asynchronously. Use the job_id from the webhook to fetch full results via the API when needed.

Tool Webhook Payload

Tool webhooks provide real-time updates for individual tool executions. You can filter events by tool ID. For example, kyb.incorporation_document_extractor provides events related to incorporation document checks in the following order:

Text extraction results (fastest)
Visual verification
Fraud detection (slowest)

Here are examples of different tool webhook payloads:

Text Extraction Results

The text extraction event is typically the fastest and includes important validation and extracted data fields:

{
  "job_id": "74f4634849d747a4b6546dfc35bdde29",
  "agent_instance_id": "c50aee83-45d6-48a2-800d-78e50ab5ea3f",
  "tool_id": "kyb.incorporation_document_extraction_tool",
  "results": {
    "explanation": "I analyzed the provided document and determined it is a valid Certificate of Incorporation for Parcha Labs, Inc. The document contains all necessary information including business name, incorporation date, registered agent address, and filing number.",
    "payload": {
      "extraction_data": {
        "is_valid_document": true,
        "analysis": "This document is a valid Certificate of Incorporation for Parcha Labs, Inc. It contains all the necessary elements of a valid incorporation document, including the business name, incorporation date, registered agent address, jurisdiction, and filing number.",
        "summary": "This document is a Certificate of Incorporation for Parcha Labs, Inc., filed with the Delaware Secretary of State on March 29, 2023. It outlines the company's basic information, including its name, registered agent, purpose, authorized shares, and various articles detailing the corporation's governance and legal matters.",
        "date": "2023-03-29",
        "alerts": null,
        "business_name": "Parcha Labs, Inc.",
        "all_business_names": [
          "Parcha Labs, Inc."
        ],
        "incorporation_date": "2023-03-29",
        "business_address": {
          "type": "Address",
          "street_1": "251 Little Falls Drive",
          "street_2": null,
          "city": "Wilmington",
          "state": "Delaware",
          "country_code": "US",
          "postal_code": "19808"
        },
        "all_extracted_addresses": {
          "registered_agent_address": {
            "type": "Address",
            "street_1": "251 Little Falls Drive",
            "street_2": null,
            "city": "Wilmington",
            "state": "Delaware",
            "country_code": "US",
            "postal_code": "19808"
          },
          "incorporator_address": {
            "type": "Address",
            "street_1": "746 4th Avenue",
            "street_2": null,
            "city": "San Francisco",
            "state": "CA",
            "country_code": "US",
            "postal_code": "94118"
          }
        },
        "business_activity": "To engage in any lawful act or activity for which corporations may be organized under the Delaware General Corporation Law",
        "jurisdiction": "Delaware",
        "business_registration_number": [
          "7379553"
        ]
      }
    },
    "passed": true,
    "answer": "The document is a valid Certificate of Incorporation for Parcha Labs, Inc., containing all necessary information for a Delaware corporation.",
    "alerts": null
  }
}

Key fields in the extraction results include:

is_valid_document: Boolean indicating if the document is a valid incorporation document
business_name: The primary name of the business
all_business_names: Array of all business names found in the document
incorporation_date: The date of incorporation
business_address: The primary business address
all_extracted_addresses: Object containing all addresses found in the document, categorized by type
business_activity: The stated purpose or activity of the business
jurisdiction: The jurisdiction where the business is incorporated
business_registration_number: Array of registration numbers found in the document

Visual Verification Results

{
  "job_id": "74f4634849d747a4b6546dfc35bdde29",
  "agent_instance_id": "92e52dec-4ec1-4dc9-8040-25d9b78a525f",
  "tool_id": "kyb.visual_verification_v3",
  "results": {
    "explanation": "Visual verification of the document features",
    "payload": {
      "visual_inspection": {
        "type": "VisualInspectionResults",
        "comparison": "The Delaware Certificate of Incorporation for Parcha Labs, Inc. is consistent with other Delaware business registration documents reviewed.",
        "reasoning": "The document's authenticity is supported by several key features: (1) The presence of the official Delaware state seal, verifying the document's origin and jurisdiction. (2) The signature of Jeffrey W. Bullock, Secretary of State of Delaware, adds further validation. (3) The document's structure, layout, and content align with the standard format for Delaware Certificates of Incorporation. (4) The absence of any visible alterations or inconsistencies further supports its authenticity.",
        "visual_analysis": {
          "document_analysis_and_classification": {
            "analysis": "The document is a Certificate of Incorporation for Parcha Labs, Inc., filed in Delaware on March 29, 2023.",
            "passed": true
          },
          "seal_verification": {
            "analysis": "The first page contains a Delaware state seal. The seal's design, text content, and unique identifiers are consistent with the expected Delaware state seal.",
            "passed": true,
            "present": true
          },
          "signature_verification": {
            "analysis": "The document contains a signature attributed to Jeffrey W. Bullock, Secretary of State of Delaware.",
            "passed": true,
            "present": true
          },
          "document_layout_and_content_verification": {
            "analysis": "The layout is consistent with a Delaware Certificate of Incorporation.",
            "passed": true
          },
          "authenticity_verification": {
            "analysis": "The document appears authentic based on the presence of the official Delaware seal.",
            "passed": true
          },
          "cross_referencing_and_consistency_check": {
            "analysis": "The business name, address, and key dates are consistent throughout the document.",
            "passed": true
          }
        },
        "inspection_passed": true,
        "summary": "Visual inspection and comparison with other Delaware business registration documents indicate that the Certificate of Incorporation is authentic."
      }
    },
    "passed": true
  }
}

Fraud Detection Results

{
  "job_id": "74f4634849d747a4b6546dfc35bdde29",
  "agent_instance_id": "8fab01c9-2a96-40ad-a01a-46e1b7a88db3",
  "tool_id": "document_fraud_check",
  "results": {
    "explanation": "The document verification analysis reveals significant concerns regarding potential fraud or tampering.",
    "payload": {
      "fraud_verification_data": {
        "verification_passed": false,
        "verification_result": "HIGH_RISK",
        "verification_data": [
          {
            "indicator_id": "has_anomalous_hsv_regions",
            "type": "RISK",
            "category": "modifications",
            "title": "Document contains regions with font color inconsistency",
            "description": "This PDF document contains characters with color artefacts distinctively different from the rest of the document."
          },
          {
            "indicator_id": "is_pdf_unmodified_per_metadata",
            "type": "TRUST",
            "category": "authenticity",
            "title": "No modification in document metadata",
            "description": "Timestamps in this document's metadata do not indicate that the file was incrementally updated or modified."
          },
          {
            "indicator_id": "is_joined_pdf",
            "type": "INFO",
            "category": "known_creator",
            "title": "PDF is likely composed of more documents",
            "description": "This document has both selectable text and image pages."
          }
        ],
        "verification_description": "The document failed the fraud verification check due to high-risk indicators."
      }
    },
    "passed": false
  }
}

HMAC Signature Verification

To ensure the security and authenticity of webhook payloads, Parcha API signs each webhook request with HMAC-SHA256 signatures. Two signatures are provided in the webhook request headers:

Standard Signature (X-Signature-SHA256): Signs the entire JSON payload
Compact Signature (parcha-signature-compact): Signs only the case ID for lightweight verification

Standard Signature Verification

The standard signature is included in the X-Signature-SHA256 header and covers the entire request body. To verify the standard signature:

Compute the HMAC-SHA256 signature of the raw request body using your API secret key.
Compare this computed signature with the one in the X-Signature-SHA256 header.

Here’s an example of how to verify the signature in Python:

import hmac
import hashlib
import base64

def verify_signature(payload, signature, api_secret_key):
    computed_signature = base64.b64encode(
        hmac.new(api_secret_key.encode('utf-8'), payload, digestmod=hashlib.sha256).digest()
    ).decode('utf-8')
    return hmac.compare_digest(computed_signature, signature)

# In your webhook handler:
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    payload = request.get_data()
    signature = request.headers.get('X-Signature-SHA256')

    if verify_signature(payload, signature, YOUR_API_SECRET_KEY):
        # Process the webhook
        data = request.json
        # ... handle the webhook data ...
        return 'Webhook received and verified', 200
    else:
        return 'Invalid signature', 401

Parcha Compact Signature

The compact signature provides a lightweight alternative for verifying webhook authenticity without needing to process the entire payload. This signature is included in the parcha-signature-compact header and signs only the case ID from input_payload.id. When to use the compact signature:

When you need quick verification before processing large payloads
When you want to validate the webhook source using only the case ID
For implementing rate limiting or deduplication based on case ID
When you need to verify webhooks in environments with limited payload access

How the compact signature is generated:

Extract the id field from input_payload in the webhook payload
Compute HMAC-SHA256 of the ID string using your API secret key
Base64 encode the resulting digest

Here’s an example of how to verify the compact signature:

import hmac
import hashlib
import base64
import json

def verify_compact_signature(payload_data, compact_signature, api_secret_key):
    """
    Verify the Parcha compact signature using only the case ID.

    Args:
        payload_data: The parsed JSON payload (dict)
        compact_signature: The signature from the parcha-signature-compact header
        api_secret_key: Your API secret key

    Returns:
        bool: True if signature is valid, False otherwise
    """
    # Extract the case ID from the payload
    case_id = payload_data.get('input_payload', {}).get('id')

    if not case_id:
        return False

    # Convert case ID to string and compute signature
    id_string = str(case_id)
    computed_signature = base64.b64encode(
        hmac.new(
            api_secret_key.encode('utf-8'),
            id_string.encode('utf-8'),
            digestmod=hashlib.sha256
        ).digest()
    ).decode('utf-8')

    # Use constant-time comparison to prevent timing attacks
    return hmac.compare_digest(computed_signature, compact_signature)

# In your webhook handler with both signatures:
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    # Get both signatures
    full_signature = request.headers.get('X-Signature-SHA256')
    compact_signature = request.headers.get('parcha-signature-compact')

    # Parse the payload
    payload_data = request.json
    raw_payload = request.get_data()

    # Option 1: Quick verification with compact signature
    if compact_signature and verify_compact_signature(payload_data, compact_signature, YOUR_API_SECRET_KEY):
        # Lightweight verification passed - process webhook
        case_id = payload_data['input_payload']['id']
        # ... quick processing based on case_id ...
        return 'Webhook received', 200

    # Option 2: Full verification with standard signature
    elif full_signature and verify_signature(raw_payload, full_signature, YOUR_API_SECRET_KEY):
        # Full verification passed - process complete payload
        # ... full processing ...
        return 'Webhook received and verified', 200

    else:
        return 'Invalid signature', 401

import crypto from 'crypto';

function verifyCompactSignature(
  payloadData: any,
  compactSignature: string,
  apiSecretKey: string
): boolean {
  /**
   * Verify the Parcha compact signature using only the case ID.
   *
   * @param payloadData - The parsed JSON payload
   * @param compactSignature - The signature from the parcha-signature-compact header
   * @param apiSecretKey - Your API secret key
   * @returns True if signature is valid, false otherwise
   */

  // Extract the case ID from the payload
  const caseId = payloadData?.input_payload?.id;

  if (!caseId) {
    return false;
  }

  // Convert case ID to string and compute signature
  const idString = String(caseId);
  const computedSignature = crypto
    .createHmac('sha256', apiSecretKey)
    .update(idString)
    .digest('base64');

  // Use constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(computedSignature),
    Buffer.from(compactSignature)
  );
}

// In your webhook handler with both signatures:
app.post('/webhook', (req, res) => {
  // Get both signatures
  const fullSignature = req.headers['x-signature-sha256'] as string;
  const compactSignature = req.headers['parcha-signature-compact'] as string;

  const payloadData = req.body;
  const rawPayload = JSON.stringify(req.body);

  // Option 1: Quick verification with compact signature
  if (compactSignature && verifyCompactSignature(payloadData, compactSignature, YOUR_API_SECRET_KEY)) {
    // Lightweight verification passed - process webhook
    const caseId = payloadData.input_payload.id;
    // ... quick processing based on case_id ...
    res.status(200).send('Webhook received');
  }

  // Option 2: Full verification with standard signature
  else if (fullSignature && verifySignature(rawPayload, fullSignature, YOUR_API_SECRET_KEY)) {
    // Full verification passed - process complete payload
    // ... full processing ...
    res.status(200).send('Webhook received and verified');
  }

  else {
    res.status(401).send('Invalid signature');
  }
});

const crypto = require('crypto');

function verifyCompactSignature(payloadData, compactSignature, apiSecretKey) {
  /**
   * Verify the Parcha compact signature using only the case ID.
   *
   * @param {Object} payloadData - The parsed JSON payload
   * @param {string} compactSignature - The signature from the parcha-signature-compact header
   * @param {string} apiSecretKey - Your API secret key
   * @returns {boolean} True if signature is valid, false otherwise
   */

  // Extract the case ID from the payload
  const caseId = payloadData?.input_payload?.id;

  if (!caseId) {
    return false;
  }

  // Convert case ID to string and compute signature
  const idString = String(caseId);
  const computedSignature = crypto
    .createHmac('sha256', apiSecretKey)
    .update(idString)
    .digest('base64');

  // Use constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(computedSignature),
    Buffer.from(compactSignature)
  );
}

// In your webhook handler with both signatures:
app.post('/webhook', (req, res) => {
  // Get both signatures
  const fullSignature = req.headers['x-signature-sha256'];
  const compactSignature = req.headers['parcha-signature-compact'];

  const payloadData = req.body;
  const rawPayload = JSON.stringify(req.body);

  // Option 1: Quick verification with compact signature
  if (compactSignature && verifyCompactSignature(payloadData, compactSignature, YOUR_API_SECRET_KEY)) {
    // Lightweight verification passed - process webhook
    const caseId = payloadData.input_payload.id;
    // ... quick processing based on case_id ...
    res.status(200).send('Webhook received');
  }

  // Option 2: Full verification with standard signature
  else if (fullSignature && verifySignature(rawPayload, fullSignature, YOUR_API_SECRET_KEY)) {
    // Full verification passed - process complete payload
    // ... full processing ...
    res.status(200).send('Webhook received and verified');
  }

  else {
    res.status(401).send('Invalid signature');
  }
});

Important notes:

The compact signature is only present when the payload contains input_payload.id
Both signatures use the same API secret key
The compact signature signs the string representation of the case ID
Always use constant-time comparison (hmac.compare_digest or crypto.timingSafeEqual) to prevent timing attacks
The compact signature is useful for quick validation, but you should still verify the full signature for complete payload integrity

Testing Your Webhooks

Parcha API provides a /api/v1/testWebhook endpoint to help you test both job and tool webhooks. This endpoint sends sample payloads to your specified webhook URLs.

curl -X POST 'https://demo.parcha.ai/api/v1/testWebhook' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "webhook_url": "https://your-webhook-url.com/job-callback",
  "tool_webhook_url": "https://your-webhook-url.com/tool-callback",
  "tool_webhook_ids": ["kyb.incorporation_document_extraction_tool"]
}'

import requests

api_key = 'YOUR_API_KEY'
url = 'https://demo.parcha.ai/api/v1/testWebhook'

data = {
    "webhook_url": "https://your-webhook-url.com/job-callback",
    "tool_webhook_url": "https://your-webhook-url.com/tool-callback",
    "tool_webhook_ids": ["kyb.incorporation_document_extraction_tool"]
}

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

response = requests.post(url, json=data, headers=headers)
print(response.json())  # {"message": "Webhook test successful"}

import axios from 'axios';

const apiKey = 'YOUR_API_KEY';
const url = 'https://demo.parcha.ai/api/v1/testWebhook';

const data = {
  webhook_url: "https://your-webhook-url.com/job-callback",
  tool_webhook_url: "https://your-webhook-url.com/tool-callback",
  tool_webhook_ids: ["kyb.incorporation_document_extraction_tool"]
};

axios.post(url, data, {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
})
.then(response => console.log(response.data))  // {"message": "Webhook test successful"}
.catch(error => console.error('Error:', error));

The test endpoint will trigger webhooks for a sample job and send appropriate payloads to your specified URLs. You can test:

Job webhooks by providing a webhook_url
Tool webhooks by providing a tool_webhook_url
Filtered tool webhooks by also including tool_webhook_ids

A successful test will return:

{
    "message": "Webhook test successful"
}

This allows you to verify your webhook implementation before processing real job events.

Best Practices

Always verify the HMAC signature to ensure the authenticity of webhook payloads.
Implement proper error handling and retries in your webhook receiver to manage potential network issues or service interruptions.
Process webhook payloads asynchronously to avoid blocking your webhook receiver.
Store the raw payload for debugging purposes before processing it.
Respond quickly to the webhook request (ideally within a few seconds) to avoid timeouts.
When using tool webhooks, be prepared to handle events in any order as different tools have different processing times.
Consider implementing separate endpoints for job webhooks and tool webhooks to simplify processing logic.

By following these guidelines and using the provided testing tools, you can ensure a robust and secure webhook integration with the Parcha API.

Getting Started

Checks Results

API Reference

Webhooks

Webhooks

Setting Up Webhooks

Webhook Payloads

Job Webhook Payload

Fetching Full Check Results

Tool Webhook Payload

Text Extraction Results

Visual Verification Results

Fraud Detection Results

HMAC Signature Verification

Standard Signature Verification

Parcha Compact Signature

Testing Your Webhooks

Best Practices

​Webhooks

​Setting Up Webhooks

​Webhook Payloads

​Job Webhook Payload

​Fetching Full Check Results

​Tool Webhook Payload

​Text Extraction Results

​Visual Verification Results

​Fraud Detection Results

​HMAC Signature Verification

​Standard Signature Verification

​Parcha Compact Signature

​Testing Your Webhooks

​Best Practices

Webhooks

Setting Up Webhooks

Webhook Payloads

Job Webhook Payload

Fetching Full Check Results

Tool Webhook Payload

Text Extraction Results

Visual Verification Results

Fraud Detection Results

HMAC Signature Verification

Standard Signature Verification

Parcha Compact Signature

Testing Your Webhooks

Best Practices