Webhook Setup

Webhooks let you react to events in real time — no polling required. Get notified instantly when orders complete, documents are ready, or entities change.

Setting Up Webhooks

Follow these steps to configure webhook endpoints in your SingleFile account:

Step 1: Access Webhook Settings

1. Log into your SingleFile account
2. At the top right corner of the screen, click the user icon to reveal a dropdown menu
3. Click on Profile Settings
4. Under the Profile tab, click on Webhook Settings

Step 2: Enable Webhook Notifications

1. Toggle the switch to the right of Webhook Notifications to activate webhook functionality
2. This allows your account to send webhook events to configured endpoints

Step 3: Add Webhook Endpoint

1. Click + Add Endpoint to create a new webhook endpoint
2. A popup dialog will appear with the following fields:

Endpoint Configuration:

• Endpoint URL: The URL where webhook events will be sent (must be HTTPS)
• Description (Optional): A description to help identify this webhook endpoint
• Event Types: Select specific events or leave empty for all events

Step 4: Configure Event Types

• For All Events: Leave the Event Types field empty to receive all webhook events
• For Specific Events: Select only the events you need to reduce noise and improve performance

New endpoints start disabled by default. Remember to enable them after creation.

Step 5: Create Endpoint

1. Click Create Endpoint to save your webhook configuration
2. The endpoint will be created in a disabled state
3. You can enable/disable endpoints as needed from the webhook settings page

Webhook Security

All webhook endpoints must use HTTPS. HTTP endpoints will be rejected.

Webhook Event Structure

All webhook events follow a consistent structure:

{
  "event_type": "order.completed",
  "order_id": "ord_12345",
  "entity_id": "ent_67890",
  "status": "completed",
  "timestamp": "2024-01-15T10:30:00Z"
}

Webhook Lifecycle

Your App                    SingleFile
   |                            |
   |   POST /webhooks endpoint  |
   |<------ event payload ------|
   |                            |
   |--- 200 OK --------------->|
   |                            |
   |   (if 5xx, retry with     |
   |    exponential backoff)    |

Handling Webhook Events

Here's how to receive and process webhook events in your application:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks", methods=["POST"])
def handle_webhook():
    event = request.json
    if event["event_type"] == "order.completed":
        process_completed_order(event["order_id"])
    return jsonify({"status": "ok"}), 200

const express = require("express");
const app = express();
app.use(express.json());

app.post("/webhooks", (req, res) => {
  const event = req.body;
  if (event.event_type === "order.completed") {
    processCompletedOrder(event.order_id);
  }
  res.status(200).json({ status: "ok" });
});

Best Practices

Endpoint Reliability: Ensure your webhook endpoint is highly available and can handle multiple concurrent requests.

Idempotency: Implement idempotency in your webhook handlers to handle duplicate events gracefully.

Error Handling: Return appropriate HTTP status codes:

• 200 OK: Event processed successfully
• 4xx: Client error (bad request, unauthorized, etc.)
• 5xx: Server error (temporary failure, retry later)

Retry Logic: SingleFile will retry failed webhook deliveries with exponential backoff. Ensure your endpoint can handle retries. For implementation patterns, see the Rate Limits section in API Basics.

Monitoring: Monitor webhook delivery success rates and set up alerts for failures.