Webhooks API

Webhooks API

CargoLint webhooks enable real-time notifications for document processing events. Instead of polling the API, webhooks deliver event data directly to your application.

Webhook access is available on Business and Enterprise plans.

Create Webhook

Register a new webhook endpoint to receive event notifications.

Endpoint

POST /webhooks

Request Schema

{
  "url": "https://example.com/webhooks/cargolint",
  "events": [
    "document.uploaded",
    "compliance.warning",
    "document.batch_downloaded"
  ],
  "active": true,
  "description": "Production webhook for document processing"
}

Request Fields

Field	Type	Required	Description
url	String	Yes	HTTPS endpoint URL to receive webhooks
events	String[]	Yes	Array of event types to subscribe to
active	Boolean	No	Enable/disable webhook (default: true)
description	String	No	Friendly description of the webhook

Example Request

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

Response Schema

{
  "id": "wh_abc123xyz789",
  "url": "https://example.com/webhooks/cargolint",
  "events": ["document.uploaded", "compliance.warning"],
  "active": true,
  "description": "Production webhook",
  "secret": "whsec_test_YOUR_WEBHOOK_SECRET_HERE",
  "createdAt": "2026-03-02T10:30:00Z"
}

List Webhooks

Retrieve all configured webhooks.

Endpoint

GET /webhooks

Example Request

curl "https://api.cargolint.com/api/v1/webhooks" \
  -H "X-API-Key: sk_test_YOUR_SECRET_KEY_HERE"

Get Webhook

Retrieve details for a specific webhook.

Endpoint

GET /webhooks/{id}

Update Webhook

Modify an existing webhook configuration.

Endpoint

PUT /webhooks/{id}

Request Schema

{
  "url": "https://example.com/webhooks/cargolint-v2",
  "events": ["document.uploaded", "compliance.warning", "document.batch_downloaded"],
  "active": true,
  "description": "Updated production webhook"
}

Example Request

curl -X PUT "https://api.cargolint.com/api/v1/webhooks/wh_abc123" \
  -H "X-API-Key: sk_test_YOUR_SECRET_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/cargolint-v2",
    "events": ["document.uploaded", "compliance.warning"],
    "active": true
  }'

Delete Webhook

Remove a webhook endpoint.

Endpoint

DELETE /webhooks/{id}

Example Request

curl -X DELETE "https://api.cargolint.com/api/v1/webhooks/wh_abc123" \
  -H "X-API-Key: sk_test_YOUR_SECRET_KEY_HERE"

Send Test Payload

Send a test webhook payload to verify your endpoint is configured correctly.

Endpoint

POST /webhooks/{id}/test

Example Request

curl -X POST "https://api.cargolint.com/api/v1/webhooks/wh_abc123/test" \
  -H "X-API-Key: sk_test_YOUR_SECRET_KEY_HERE"

Webhook Delivery History

Retrieve delivery history and logs for a webhook.

Endpoint

GET /webhooks/{id}/deliveries

Query Parameters

Parameter	Type	Default	Description
offset	Integer	0	Number of items to skip
limit	Integer	20	Maximum items to return

Example Request

curl "https://api.cargolint.com/api/v1/webhooks/wh_abc123/deliveries?limit=10" \
  -H "X-API-Key: sk_test_YOUR_SECRET_KEY_HERE"

Supported Event Types

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

Webhook Payload Format

All webhook events follow this payload structure:

{
  "event": "document.uploaded",
  "timestamp": "2026-03-02T11:45:00Z",
  "webhookId": "wh_abc123",
  "deliveryId": "dlv_xyz789",
  "data": {
    "document": {
      "id": "doc_abc123",
      "fileName": "invoice.pdf",
      "documentType": "invoice",
      "status": "processing"
    }
  }
}

Signature Verification

Each webhook request includes a signature header for verification:

X-CargoLint-Signature: sha256=abcdef1234567890

Verify signatures using your webhook secret:

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.

Best Practices

• Always verify webhook signatures before processing
• Respond to webhooks within 30 seconds to avoid timeout
• Implement idempotent processing to handle duplicate deliveries
• Monitor delivery history for failed webhooks
• Use test endpoint before deploying to production
• Rotate webhook secrets periodically for security