# Webhook Input Integration – Testing with Postman Request

### Overview 

Webhook Input allows external systems to send documents to Docspire for processing via HTTP POST requests. This enables automated document ingestion from third-party applications, custom workflows, or any system capable of making HTTP calls. 

Common use cases include triggering document processing from CRM systems, integrating with document management platforms, automating invoice processing from email attachments, and building custom upload portals. 

### Prerequisites 

Before setting up webhook input, ensure you have: 

* Administrator access to your Docspire organization 
* An external system capable of sending HTTP POST requests 
* Documents in supported formats (PDF, DOCX, PNG, JPG) 

### Configuring Webhook Input 

#### Step 1: Access Webhook Configuration 

1. Navigate to **Automation > Integrations** in the left sidebar. 
2. Locate the **Webhooks** card in the Available Integrations section. 
3. Click **Configure** to open the Webhook Configuration dialog. 

<figure><img src="https://3990462849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fgjpo1gyiI3QKDSNO9maQ%2Fuploads%2Fsi9xjvKrr14iZXGYDggW%2F1.png?alt=media&#x26;token=8ce78a67-b979-455d-b416-6195ebabaff2" alt=""><figcaption></figcaption></figure>

#### Step 2: Generate Webhook Credentials&#x20;

1. Select the **Webhook Input** tab.&#x20;
2. Click **Save Configuration** to generate your webhook credentials.&#x20;
3. The system will generate two credentials:&#x20;

| **Credential** | **Description**                                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
| Secret Key     | Authentication token required in the X-Docspire-Secret header of all requests                                       |
| Webhook URL    | The endpoint URL where documents should be sent (e.g., <https://server.docspire.ai/d/integrations/webhook/receive>) |

<figure><img src="https://3990462849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fgjpo1gyiI3QKDSNO9maQ%2Fuploads%2FcnSETmFYdqw7KxEz8eej%2Fimage.png?alt=media&#x26;token=6b17cc99-a1de-4f41-9750-76d08843c4a8" alt="" width="563"><figcaption></figcaption></figure>

#### Step 3: Copy Your Credentials&#x20;

In the **Webhook Credentials** section:&#x20;

1. Click **Copy** next to the **Secret Key** field to copy your authentication token.&#x20;
2. Click **Copy** next to the **Webhook URL** field to copy your endpoint URL.&#x20;
3. Store these credentials securely. You will need them to configure your external system.&#x20;

### API Specification&#x20;

When sending documents to Docspire, your request must include:

| **Property**    | **Value**                            |
| --------------- | ------------------------------------ |
| HTTP Method     | POST                                 |
| Content-Type    | multipart/form-data                  |
| Required Header | X-Docspire-Secret: {your-secret-key} |

#### Request Body Fields

| **Field**    | **Type** | **Required** | **Description**                                                                     |
| ------------ | -------- | ------------ | ----------------------------------------------------------------------------------- |
| files        | File\[]  | Yes          | One or more document files to process                                               |
| DocumentType | String   | No           | Specify the document type (e.g., Invoice, Receipt). Leave empty for auto-detection. |
| BusinessId   | String   | No           | Your internal reference ID (max 50 characters)                                      |

### Example: Sending Documents with Postman&#x20;

This example demonstrates how to send a document to Docspire and retrieve the processing results using Postman.&#x20;

#### Part 1: Send a Document for Processing&#x20;

4. Open Postman and create a new request.&#x20;
5. Set the request method to **POST**.&#x20;
6. Paste your **Webhook URL** in the request URL field.&#x20;
7. Go to the **Headers** tab and add a new header:&#x20;

| Key               | Value             |
| ----------------- | ----------------- |
| X-Docspire-Secret | {your-secret-key} |

<div data-with-frame="true"><figure><img src="https://3990462849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fgjpo1gyiI3QKDSNO9maQ%2Fuploads%2FmI5v6Xwf9Y1jAXkuxYSe%2F2.webp?alt=media&#x26;token=167cf2d7-b6a8-458f-9c69-37bba0b0b8c2" alt=""><figcaption></figcaption></figure></div>

8. Go to the **Body** tab and select **form-data**.&#x20;
9. Add a new key named **files**. Change the type from "Text" to **File** using the dropdown.&#x20;
10. Click **Select Files** and choose the document you want to process.&#x20;
11. Click **Send** to submit the request.&#x20;

<div data-with-frame="true"><figure><img src="https://3990462849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fgjpo1gyiI3QKDSNO9maQ%2Fuploads%2FBugjCdHRapLEeUPyQwdG%2F3.png?alt=media&#x26;token=68d05eae-364d-49bc-9073-1a547b95ef08" alt=""><figcaption></figcaption></figure></div>

You will receive a JSON response confirming the document was received:

<div data-with-frame="true"><figure><img src="https://3990462849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fgjpo1gyiI3QKDSNO9maQ%2Fuploads%2FPSKWTTdHVfkoRhKvZYLF%2F4.png?alt=media&#x26;token=19af4f20-60fa-4bd8-8faf-c956565a76e6" alt=""><figcaption></figcaption></figure></div>

#### Part 2: Retrieve Processing Results&#x20;

4. From the response above, copy the **documentId** value.&#x20;

<div data-with-frame="true"><figure><img src="https://3990462849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fgjpo1gyiI3QKDSNO9maQ%2Fuploads%2F9GByitc5geihbgPBSxUI%2F5.png?alt=media&#x26;token=8127a44f-3fc2-4efa-81ef-1e455db33a44" alt=""><figcaption></figcaption></figure></div>

5. Create a new request in Postman.&#x20;
6. Set the request method to **GET**.&#x20;
7. Construct the URL by appending the document ID to the process endpoint:&#x20;

`https://server.docspire.ai/d/integrations/webhook/process/{documentId}`&#x20;

Example:&#x20;

`https://server.docspire.ai/d/integrations/webhook/process/9680fe06-3803-49e9-95c4-50035ea13775`&#x20;

8. Go to the **Headers** tab and add the same authentication header:&#x20;

| **Key**           | **Value**         |
| ----------------- | ----------------- |
| X-Docspire-Secret | {your-secret-key} |

9. Click **Send** to retrieve the processing results.&#x20;
10. The response will contain the extracted data along with accuracy details for each field.&#x20;

<div data-with-frame="true"><figure><img src="https://3990462849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fgjpo1gyiI3QKDSNO9maQ%2Fuploads%2FUiTcsH7GpsmrfLvv9Jjo%2F6.png?alt=media&#x26;token=5b6c8868-5085-4a4e-9d64-b5fc60c6b4e2" alt=""><figcaption></figcaption></figure></div>

#### Part 3: Verify in Document Queue&#x20;

You can also verify document processing in the Docspire interface:&#x20;

4. Navigate to **Main > Document Queue** in the left sidebar.&#x20;
5. Look for your document in the list. It will show with a **Running** status while processing.&#x20;

<figure><img src="https://3990462849-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fgjpo1gyiI3QKDSNO9maQ%2Fuploads%2FywpYzxpSZQyQ4bAk8Y0p%2F7.webp?alt=media&#x26;token=c4c620b5-d505-403e-a06f-03a3bced5fa7" alt=""><figcaption></figcaption></figure>

6. Once processing completes, the status changes to **Success** or **In Review**.&#x20;
7. Click **View Results** to see the extracted data in the interface.&#x20;

### Regenerating Credentials&#x20;

If you need to rotate your credentials for security purposes:&#x20;

13. Open the Webhook Configuration dialog.&#x20;
14. Click **Regenerate Credentials**.&#x20;
15. Update all connected systems with the new Secret Key.&#x20;

> <mark style="color:$danger;">Warning</mark>: Regenerating credentials immediately invalidates the old Secret Key. All systems using the old credentials will receive authentication errors until updated.&#x20;

### Troubleshooting&#x20;

| **Issue**                              | **Solution**                                                                     |
| -------------------------------------- | -------------------------------------------------------------------------------- |
| 401 Unauthorized                       | Verify the X-Docspire-Secret header contains the correct Secret Key.             |
| 400 Bad Request                        | Ensure Content-Type is multipart/form-data and the files field is present.       |
| Document not appearing in queue        | Check the response for rejectionReason. Verify file format is supported.         |
| Processing stuck on Running            | Large or complex documents may take longer. Check Document Tracking for details. |
| Invalid credentials after regeneration | Update all connected systems with the new Secret Key.                            |

### Related Features&#x20;

* **Document Queue** – View and manage documents received via webhook.&#x20;
* **Document Tracking** – Monitor the processing status of webhook-submitted documents.&#x20;
* **Webhook Output Integration** – Send processed results to external systems.&#x20;
* **Process Notifications** – Set up alerts for webhook-related processing events.&#x20;