Webhook

Overview

The Webhook Integration feature enables Docspire to send and receive documents via HTTP webhooks, providing a flexible API-based approach for integrating with external systems. Webhooks support two directions of data flow:

• Webhook Input – Receive documents from external systems into Docspire for processing

• Webhook Output – Send processed document data from Docspire to external systems (CRMs, ERPs, databases, etc.)

This guide covers how to configure both webhook input and output integrations.

Prerequisites

Before setting up webhook integrations, ensure you have:

• Administrator access to your Docspire organization

• For Webhook Input: An external system capable of sending HTTP POST requests

• For Webhook Output: The target endpoint URL and any required authentication credentials

Accessing Webhook Configuration

1. Navigate to Automation > Integrations in the left sidebar.

2. Locate the Webhooks card in the Available Integrations section.

3. Click the Configure button to open the Webhook Configuration dialog.

The configuration dialog contains two tabs: Webhook Input and Webhook Output. Select the appropriate tab based on your integration needs.

Part 1: Configuring Webhook Input

Webhook Input allows external systems to send documents to Docspire for processing via HTTP POST requests. When configured, Docspire generates a unique endpoint URL and secret key for secure authentication.

1. Select the Webhook Input tab in the configuration dialog.

2. Click Save Configuration to generate your webhook endpoint URL and secret key.

The system will display your credentials in the Webhook Credentials section.

Once generated, the following credentials are displayed:

Credential	Description
Secret Key	A unique authentication token that must be included in the X-Docspire-Secret header of incoming requests.
Webhook URL	The endpoint URL where external systems should send document payloads (e.g., http://listener.docspire.ai/docspire/integrations/webhook/receive).

1. Use the Copy buttons to copy each value to your clipboard. A ready-to-use cURL Example is also provided at the bottom of the dialog for quick testing.

1. When sending documents to the webhook endpoint, use the following specifications:

Content-Type: multipart/form-data

Form Fields:

Field	Type	Required	Description
files	File[]	Yes	Document files to process
DocumentType	string	No	Document type from DocumentTypeInfo (validated if provided)
AllowedDocumentTypes	string	No	Optional comma-separated document type allow-list for this request
BusinessId	string	No	Business identifier (alphanumeric, underscore, hyphen; max 50 chars)

Required Headers:

Header	Description
X-Docspire-Secret	Shared secret for webhook input authentication (must match the configured Secret Key)

1. If you need to rotate your credentials for security purposes, click the Regenerate Credentials button.

Important: Regenerating credentials will invalidate your existing webhook integration. Make sure to update any systems using the old credentials.

Part 2: Configuring Webhook Output

Webhook Output allows Docspire to send processed document data to external systems automatically. You can configure multiple output webhooks to deliver data to different destinations such as CRMs, ERPs, databases, or custom applications.

1. Select the Webhook Output tab in the configuration dialog.

2. In the Webhook Endpoint section, fill in the following fields:

Field	Description
Integration Name	A descriptive name for the integration (e.g., CRM Webhook, ERP Integration). Optional but recommended.
Webhook URL *	The target endpoint URL where processed data will be sent (e.g., https://api.example.com/webhook).
HTTP Method *	The HTTP method to use for requests. Select from the dropdown (typically POST).

1. In the Authentication section, select the appropriate authentication method from the Auth Type dropdown.

If your target system uses a legacy token-based authentication, you can optionally provide a Legacy Bearer Token.

Each authentication type comes with its own set of credentials.

Auth Type	Description
No Authentication	No authentication headers are added to requests
NTLM	Windows NT LAN Manager authentication for Windows-based systems
API Key	API key-based authentication, typically sent as a header or query parameter
Basic Authentication	Username and password encoded in Base64
OAuth 2	OAuth 2.0 token-based authentication for modern APIs
Bearer Token	JWT or opaque bearer token authentication
AWS Signature	AWS Signature Version 4 for Amazon Web Services endpoints

1. (Optional)The Custom Headers section allows you to add additional HTTP headers to outgoing requests:

   1. Click + Add Header to add a new header entry.

   2. Enter the header name and value.

   3. Repeat for additional headers as needed.

These headers will be injected into every outgoing request to the configured endpoint.

1. Click Save Configuration to activate the webhook output integration. The integration will appear in the Active Integrations section at the bottom of the Integrations page.

Managing Active Webhook Integrations

All configured webhooks appear in the Active Integrations section at the bottom of the Integrations page.

Each entry displays:

• Integration type – Webhook Input or Webhook Output

• Direction – Input Source (for incoming documents) or Output Source (for outgoing data)

• Connected URL – The endpoint URL associated with the integration

• Delete button – Removes the integration and stops data transmission

You can configure multiple webhook output integrations to send data to different destinations simultaneously.

Best Practices

• Secure your credentials – Store your webhook secret key securely and never expose it in client-side code or public repositories.

• Use HTTPS endpoints – Always configure output webhooks to use HTTPS URLs for encrypted data transmission.

• Implement proper authentication – Choose the appropriate authentication method based on your target system's security requirements.

• Rotate credentials regularly – Periodically regenerate webhook input credentials and update connected systems accordingly.

• Test before production – Use the provided cURL example to test webhook input integrations before deploying to production.

• Use descriptive integration names – Give webhook outputs meaningful names (e.g., "CRM Webhook", "ERP Integration") for easy identification.

Troubleshooting

Issue	Solution
Webhook input returns 401 Unauthorized	Verify the X-Docspire-Secret header matches the configured Secret Key exactly.
Documents not appearing in queue	Ensure the files field contain valid document files and the Content-Type is multipart/form-data.
Webhook output fails to deliver	Check that the target URL is accessible and the authentication credentials are correct.
Connection timeout on output	Verify the target endpoint is responding and not blocked by firewalls.
Invalid credentials after regeneration	Update all connected systems with the new Secret Key after regenerating credentials.

Related Features

• Document Queue – View and manage documents received via webhook input source.

• Document Tracking – Monitor the processing status of documents received through webhooks.

• Process Notifications – Set up alerts for webhook-related processing events.

• Workflow – Configure automated processing pipelines that trigger webhook outputs upon completion.