Webhooks

ColiVara supports Webhookw for asynchronous document upsertion. If not set up, you will receive an email on document upsertion failures only. If setup, you will receive events for success and failure. You can create and verify the Webhook using our provided SDK, or via the User Interface at www.colivara.com.

Webhooks can be useful to manage downstream event handling and knowing when the documents are ready to query. They are especially useful when upserting documents more than 100 pages in length or when waiting for upsertion is not efficient.

Setting up a webhook via the User Interface (Recommended)

1

Visit your Account Dashboard

Via https://colivara.com/accounts/edit-account/

2

Enter your webhook URL

Make sure that your URL enpoint is Publicly Available

3

Store your Webhook Secret

Setting up a web hook via the SDK (Alternative)

The Python SDK library provides the method to register a webhook URL

add_webhook

Parameters:

• url(str): The URL of the webhook endpoint to register. This must be a valid, publicly accessible URL.

Returns:

• WebhookOut: An object containing details about the registered webhook, including the webhook ID, associated app ID, and webhook secret.

Exceptions:

• ValueError: Raised if the provided URL is invalid or the request is rejected due to a bad request (e.g., missing or incorrect parameters).

• requests.HTTPError: Raised for other HTTP errors, such as server-side issues.

Example:

# Register a webhook to handle document upsertion events
webhook = client.add_webhook(
    url="https://your-domain.com/webhook-handler"
)

Verifying Webhook from inside your application

Now that ColiVara have noted your app URL to send notification to, you will start receiving HTTP request containing information regarding your document process status.

However, prior to ingesting the data from these HTTP requests, you should validate the webhook to verify that it truly comes from ColiVara. Afterall, any malicious actor can send an HTTP request to a publicly available URL. Your webhook secret is a unique key used to verify that incoming webhook requests are authentic. This protects your application from unauthorized or fake notifications.

Keep your webhook secret safe and never share it publicly. If exposed, attackers could forge requests and compromise your system.

The SDK provides a method that you can use to validate the webhook from inside your Python application

validate_webhook:

Parameters:

• webhook_secret (str): The secret key provided when the webhook was registered. Used for validation.

• payload (str): The raw body of the incoming webhook request.

• headers (Dict[str, Any]): The headers from the incoming webhook request, which include the signature used for validation.

Returns:

• bool: Returns True if the webhook is valid; otherwise, returns False.

Example:

# Validate an incoming webhook request
is_valid = client.validate_webhook(
    webhook_secret="your_webhook_secret",
    payload=raw_payload,
    headers=request_headers
)

if is_valid:
    print("Webhook is valid!")
else:
    print("Invalid webhook!")