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

Webhooks are enabled per account by SingleFile. If you do not see Webhook Settings in your profile, ask your SingleFile contact to turn the feature on for your organization. Only organization administrators can configure endpoints.

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

Step 1: Access Webhook Settings

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

Step 2: Enable Webhook Notifications

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

Step 3: Add Webhook Endpoint

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

Endpoint Configuration:

Endpoint URL: The URL where webhook events will be sent. Use HTTPS; your endpoint will receive customer data.
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

The event names below are the event_name values delivered in the payload.

Category	Event name	Trigger
Entities	`entity.created`	Entity created
Entities	`entity.updated`	Entity updated
Documents	`document.created`	Document available (including a filed document or an EIN letter attached to an entity)
Documents	`document.updated`	Document updated
Documents	`document.deleted`	Document deleted
Jurisdictions	`jurisdiction.created`	Jurisdiction added to an entity
Jurisdictions	`jurisdiction.updated`	Jurisdiction updated
Tasks	`task_instance.created`	Task created for an entity
Orders	`order.submitted`	Order received
Orders	`order.cancelled`	Order cancelled
Orders	`order.completed`	Order completed
Orders	`order.document.created`	Document uploaded with an order document request
Orders	`order.document.request.status_change`	Order document request status changed
Signatures	`signature.requested`, `signature.completed`, `signature.declined`, `signature.expired`	Send-for-signature lifecycle; delivered to endpoints with no event filter

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

Step 5: Create Endpoint

Click Create Endpoint to save your webhook configuration
The endpoint is active immediately unless you ticked Start disabled
You can enable/disable endpoints as needed from the webhook settings page

Webhook Security

🛡️
Deliveries are signed, but the signing secret is not currently exposed in SingleFile, so signature verification is not yet available to you. Until it is, use an unguessable endpoint path over HTTPS and treat the payload as a notification: confirm state by calling the API (for example GET /orders/{id}) before acting on it.

Webhook Event Structure

Every delivery is a JSON object with three keys: event_name, object_type (order, entity, document, jurisdiction or order_document_request) and object, the full record as the matching detail endpoint returns it.

{
  "event_name": "order.completed",
  "object_type": "order",
  "object": {
    "id": "24804521-cebd-4086-acc9-48229b4380d6",
    "order_id": "LvGstOBQ-KDr0YJ8T",
    "status": "completed",
    "filing_type": "EIN",
    "entity": { "id": "e4e0f6ce-6e79-4de8-a51f-84e1f0a42794" },
    "status_history": [
      { "status": "received", "timestamp": "2026-10-19T18:24:05.412993-07:00" },
      { "status": "completed", "timestamp": "2026-10-21T09:12:40.000000-07:00" }
    ]
  }
}

All ids are UUIDs. For a document.* event, object is the document record, including entity_id and document_type.

Webhook Lifecycle

Your App                    SingleFile
   |                            |
   |   POST /webhooks endpoint  |
   |<------ event payload ------|
   |                            |
   |--- 200 OK --------------->|
   |                            |
   |   (any non-2xx or timeout: |
   |    retried on a schedule)  |

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_name"] == "order.completed":
        process_completed_order(event["object"]["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_name === "order.completed") {
    processCompletedOrder(event.object.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: A delivery that does not get a 2xx response within the timeout is retried automatically on a fixed schedule over roughly the following day (several attempts in the first hours, then spaced out). Respond 2xx quickly and do the work asynchronously; a 4xx is retried the same as a 5xx.

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