​
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:

  1. Job Webhooks (webhook_url): Receive notifications when the entire job is completed
  2. 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://demo.parcha.ai/runCheck' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "agent_key": "your-agent-key",
  "check_id": "kyb.incorporation_document_verification",
  "payload": {
    "document_url": "https://example.com/document.pdf"
  },
  "webhook_url": "https://your-webhook-url.com/job-callback",
  "tool_webhook_url": "https://your-webhook-url.com/tool-callback"
}'

​
Webhook Payloads

​
Job Webhook Payload

When a job is completed, Parcha API sends a POST request to your webhook URL with a payload containing the final job results:

{
  "updated_at": "2024-09-18T18:31:05.094700",
  "id": "e85e0cc4-b1e8-40b0-9a3d-83c328eee0f4",
  "agent_id": "remediation-v1",
  "status": "complete",
  "check_results": [
    {
      "command_id": "kyb.incorporation_document_verification",
      "status": "complete",
      "payload": {
        "document_verification": {
          "verification_passed": true,
          "verification_summary": "Document appears authentic and valid",
          "extracted_data": {
            "company_name": "Parcha Labs, Inc.",
            "incorporation_date": "2023-03-29",
            "jurisdiction": "Delaware"
          }
        }
      }
    }
  ]
}

​
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:

  1. Text extraction results (fastest)
  2. Visual verification
  3. 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 an HMAC-SHA256 signature. This signature is included in the X-Signature-SHA256 header of the webhook request.

To verify the signature:

  1. Compute the HMAC-SHA256 signature of the raw request body using your API secret key.
  2. 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

​
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"]
}'

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

  1. Always verify the HMAC signature to ensure the authenticity of webhook payloads.
  2. Implement proper error handling and retries in your webhook receiver to manage potential network issues or service interruptions.
  3. Process webhook payloads asynchronously to avoid blocking your webhook receiver.
  4. Store the raw payload for debugging purposes before processing it.
  5. Respond quickly to the webhook request (ideally within a few seconds) to avoid timeouts.
  6. When using tool webhooks, be prepared to handle events in any order as different tools have different processing times.
  7. 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.