Webhook Upload

Overview

1Flow provides a webhook endpoint that allows you to programmatically upload documents via HTTP POST requests. This is ideal for integrating with external systems, automated workflows, or custom applications.

How It Works

When you send a document to your webhook URL:

1. Authentication - Request is validated using your webhook secret (if configured)
2. File Upload - Document is uploaded to secure storage
3. Pre-processing - Spreadsheet files (Excel, CSV) are automatically converted to CSV text format
4. Document Processing - The document goes through the standard pipeline:
   • Classification
   • Folder assignment
   • Data extraction
   • Indexing for search

Webhook URL Format

POST https://app.1flow.io/api/webhook/{webhookId}/document/upload

Where {webhookId} is your unique webhook identifier.

Example:

POST https://app.1flow.io/api/webhook/abc123xyz/document/upload

API Reference

Endpoint

POST /api/webhook/{webhookId}/document/upload

Authentication

If a webhook secret is configured, include it in the Authorization header:

Authorization: {your-webhook-secret}

Request Formats

You can send documents in three ways:

curl -X POST https://app.1flow.io/api/webhook/{webhookId}/document/upload \
  -H "Authorization: {your-webhook-secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/documents/invoice.pdf"
  }'

Response Format

Success Response (200):

{
  "success": true,
  "message": "Document uploaded successfully",
  "documentId": "doc_abc123xyz"
}

Error Responses:

• 401 Unauthorized - Invalid or missing webhook secret
• 404 Not Found - Invalid webhook ID
• 400 Bad Request - Missing or invalid file data, unsupported file type, or unable to determine content type

Example Error Response:

{
  "success": false,
  "error": "Unable to determine content type. Please provide 'contentType' in the request body or ensure the file has a recognized extension."
}

Supported File Types

• PDF documents - Invoices, receipts, bank statements, etc.
• Image files - JPG, JPEG, PNG, GIF, WebP, TIFF
• Spreadsheet files - Excel (XLS, XLSX, XLSM) and CSV files (automatically converted to CSV text)

Code Examples

async function uploadDocumentFromUrl(
  url: string,
  webhookId: string,
  secret: string
) {
  const response = await fetch(
    `https://app.1flow.io/api/webhook/${webhookId}/document/upload`,
    {
      method: 'POST',
      headers: {
        'Authorization': secret,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        url: url,
      }),
    }
  );

  const result = await response.json();
  return result.documentId;
}

Troubleshooting

401 Unauthorized

• Verify your webhook secret matches the one in Organization Settings
• Ensure the Authorization header is included in the request
• Check that the secret doesn't have extra spaces or characters

404 Not Found

• Verify the webhook ID in your URL matches the one in Organization Settings
• Ensure you're using the correct endpoint path: /api/webhook/{webhookId}/document/upload
• Check that you're using the correct base URL (https://app.1flow.io)

400 Bad Request

• Verify the file is a supported format (PDF, image, or spreadsheet)
• Check that the file data is properly formatted
• Ensure required fields (file or url) are included
• If using JSON, verify the base64 encoding is correct
• Check that the URL is accessible and returns a valid file (for URL-based uploads)
• Ensure content type can be determined (provide contentType if needed)

Upload + Polling Pattern

After uploading a document, you'll need to poll the get endpoint to check when processing is complete and retrieve the extracted data. See the Upload + Polling Pattern guide for complete implementation details and code examples.

Next Steps

• Learn about retrieving documents to check status and get extracted data
• Explore deleting documents for document management
• Set up webhook callbacks to receive notifications when documents are processed
• Check out email uploads for email-based document submission
• Explore the Browse App to view your uploaded documents