Webhook Setup Guide

Overview

Webhooks allow your system to receive real-time notifications when CargoLint processes documents. This guide walks you through configuring, testing, and monitoring webhooks.

Webhook access is available on Business and Enterprise plans.

Creating a Webhook

Via User Interface

1. Navigate to Settings > Integrations > Webhooks
2. Click Add Webhook
3. Enter your endpoint URL (must use HTTPS)
4. Select which events trigger notifications
5. Click Create Webhook

Via API

curl -X POST https://api.cargolint.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhooks/cargolint",
    "events": ["document.uploaded", "compliance.warning"],
    "active": true,
    "description": "Production webhook"
  }'

Supported Events

• document.uploaded - Document successfully uploaded
• compliance.warning - Compliance issues detected during processing
• document.batch_downloaded - Batch documents downloaded as ZIP

Webhook Security

Each webhook delivery is signed with HMAC-SHA256. Verify signatures using the secret returned when you create the webhook:

X-CargoLint-Signature: sha256=abcdef1234567890

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature.split('=')[1])

Security Warning: Always use hmac.compare_digest() (or equivalent constant-time comparison function) for signature verification. Do not use == for comparison, as this is vulnerable to timing attacks that could allow an attacker to forge valid signatures.

Testing Your Webhook

1. In the webhook settings, click Send Test Payload
2. Verify your endpoint returns HTTP 200
3. Check delivery status in the delivery history

Monitoring Deliveries

The Delivery History section shows:

• Timestamp of each delivery attempt
• Response status code
• Retry count

Handling Failed Deliveries

CargoLint automatically retries failed webhooks. After multiple failed attempts, the webhook is disabled and marked as failed.

Troubleshooting

Webhook not receiving events:

• Verify endpoint is publicly accessible via HTTPS
• Check firewall/proxy configurations
• Review delivery history for error messages

High failure rate:

• Check your endpoint’s response time
• Ensure HTTP 200 response is sent immediately
• Review server logs for connection errors