Pipeline Webhooks

Webhooks enable real-time notifications when documents are processed in your Vectorize pipelines. This guide shows you how to create, configure, and manage webhooks to integrate your pipelines with external systems.

Overview

Webhooks are HTTP callbacks that notify your applications when documents are successfully processed and vectorized in your pipeline. When a document completes processing, Vectorize sends a POST request to your configured endpoint with details about the document and its metadata.

Creating Your First Webhook

Step 1: Navigate to Webhook Creation

1. Go to Pipelines in the main navigation
2. Select your pipeline from the list
3. Navigate to the Webhooks tab
4. Click Create New Webhook

Step 2: Configure Basic Settings

Enter the core webhook configuration:

• Webhook Name: A descriptive name
• Webhook URL: The HTTPS endpoint that will receive POST requests
• Webhook Secret (optional): A shared secret for payload signature verification

Step 3: Generate a Secure Secret (Optional)

For production webhooks, we recommend using a webhook secret:

1. Click the Generate button next to the secret field
2. Vectorize creates a cryptographically secure random secret
3. Copy this secret - you'll need it to verify webhook payloads in your application
4. The secret is stored encrypted in AWS Parameter Store
5. Vectorize signs each webhook payload with HMAC-SHA256 and sends it in the X-Webhook-Signature header

Important: Store your webhook secret securely. It cannot be retrieved after creation, only replaced.

Step 4: Select Trigger Events

Select the events that should trigger the webhook:

Event	Description	Payload Includes
Document Processed	Document fully processed and vectorized	Document ID, metadata, processing stats
Document Processing Error	Document processing failed	Error details, document ID

Step 5: Save and Activate

1. Click Create Webhook to save your configuration
2. The webhook is created in active status by default
3. It will begin receiving events immediately

Webhook Payload Format

Document Processed Event

When a document is successfully processed, your endpoint receives:

{
  "event_type": "pipeline.document.processed",
  "pipeline_id": "8a95afae-7509-427a-8073-4917a77afcc2",
  "document_id": "doc-uuid",
  "timestamp": "2025-09-17T13:46:34.244666+00:00",
  "correlation_id": "cd9459a9-e498-4849-a1f2-cda17e9af5e2",
  "status": "success",
  "metadata": {
    "source": "google_drive",
    "file_name": "document.pdf"
  }
}

Webhook Headers

Every webhook request includes:

• Content-Type: application/json
• User-Agent: LangStream-webhook/1.0
• X-Webhook-ID: Unique webhook identifier
• X-Webhook-Type: Event type (e.g., pipeline.document.processed)
• X-Webhook-Signature: HMAC-SHA256 signature (if secret configured)
• X-Timestamp: ISO 8601 timestamp
• X-Idempotency-Key: Unique key for deduplication
• Your custom headers (if configured)

Managing Webhooks

Viewing Webhook Status

From your pipeline's Webhooks tab, you can see:

• Webhook name and URL
• Status (active, inactive, error)
• Success/failure counts
• Last triggered timestamp

Viewing Delivery Logs

Click on View Logs to see:

• Failed delivery attempts
• Response status codes
• Response times
• Error messages
• Full request payloads

Note: Only failed deliveries are logged. Successful deliveries (2xx status codes) are counted but not logged in detail.

Deactivating Webhooks

To temporarily stop webhook deliveries without deleting:

1. Edit the webhook
2. Change status to Inactive
3. Save changes

The webhook configuration is preserved and can be reactivated later.

Deleting Webhooks

To permanently remove a webhook:

1. Click the Delete button
2. Confirm deletion

This action cannot be undone.

Testing Webhooks

To test your webhook configuration:

1. Click Test Webhook from the webhook details
2. Vectorize sends a test payload to your endpoint
3. View the response status and details
4. Check delivery logs for any issues

Test payload example:

{
  "event": "webhook.test",
  "timestamp": "2024-10-08T15:00:00Z",
  "message": "This is a test webhook from Vectorize",
  "webhook": {
    "id": "webhook-123",
    "name": "Your Webhook Name"
  }
}

What's Next?

• Learn about pipeline configuration to understand event sources
• Explore metadata extraction for richer webhook payloads