How to set up webhooks in SparkReceipt

What webhooks do

A webhook lets SparkReceipt push your document data to your own systems automatically. Whenever a document — an expense, income document, or bank statement — is created, updated, or deleted in your account, SparkReceipt sends an HTTP POST request with a JSON payload to a URL you configure. The payload contains the document's extracted data (vendor, date, totals, taxes, categories, tags, line items, and more) plus download links to the original files.

This is the building block for custom integrations: route new receipts into your own database, trigger a Zapier or Make scenario, copy files to cloud storage, or notify your team's chat when a large invoice arrives.

Setting up a webhook

Webhooks are included in SparkReceipt's paid plans. Webhook settings are available to account owners, admins, and users with the Accountant role.

1. In the SparkReceipt web app, open Settings and select Integrations.
2. Scroll to the Webhooks section.
3. Click Add webhook.
4. Enter the receiving URL and make sure Enabled is switched on.
5. Save the webhook. Its status on the Integrations page changes to Active.

A few requirements for the URL:

• It must be a valid, publicly reachable HTTP or HTTPS address. URLs that point to private or internal network addresses are rejected for security reasons.
• Your endpoint should respond with a 2xx status code (for example 200 OK) to acknowledge the delivery. Any other response is recorded as a failed delivery.

Each SparkReceipt account supports one webhook. If you need to fan events out to several systems, point the webhook at an automation tool (like Zapier or Make) or a relay endpoint of your own and distribute from there.

When the webhook fires

The webhook fires on three events: created, updated, and deleted. Every document in the account triggers it — there is currently no way to subscribe to only a subset of events or document types.

Deliveries are delayed and batched rather than sent instantly. By default, SparkReceipt waits about 5 minutes after an event before calling your endpoint, and all changes to the same document within that window are combined into a single call (the settings page shows the current delay for your account):

• If a document is created and then edited right away — for example, you fix the vendor name just after scanning — you receive one created event containing the final data.
• If a document is created and deleted within the window, the events cancel out and nothing is sent.
• Separate changes to the same document outside the window arrive as separate updated events.

This batching means your automation doesn't get flooded with intermediate states while a document is still being processed and reviewed.

The payload

Each delivery is a POST request with Content-Type: application/json. The top level of the payload identifies the account, the event, and the entity; created and updated events include the full document object, while deleted events include only the document_id.

Here is an abbreviated example of a created event for an expense:

{
  "organization_id": "7b54b45b-a813-41e9-ad67-27d504382072",
  "organization_name": "Acme Corp",
  "task_id": "59dc4c27-389a-42a9-a42b-f49745274dad",
  "entity": "document",
  "event": "created",
  "task_created_at": "2026-07-16T12:34:00Z",
  "task_sent_at": "2026-07-16T12:39:00Z",
  "document": {
    "id": "3a964309-b83d-495c-8f4f-84d395947e7f",
    "name": "Invoice #1001",
    "date": "2026-06-30",
    "description": "Consulting services",
    "currency_code": "USD",
    "reference_number": "INV-1001",
    "raw_text": "Text extracted from the document...",
    "review_status": "reviewed",
    "input_source": "inbound_email",
    "user": {
      "id": "3328431d-3bd6-418b-9f70-634480d9739a",
      "email": "user@example.com",
      "name": "Jane Doe",
      "role": "admin",
      "status": "active"
    },
    "trashed": false,
    "files": [
      {
        "id": "319e266d-0ba9-4d15-8587-5769d5d20ef5",
        "malware_blocked": false,
        "preview_url": "https://...",
        "url": "https://...",
        "filename": "invoice.pdf",
        "content_type": "application/pdf"
      }
    ],
    "primary_category": "expense",
    "secondary_category": {
      "id": "c7b48b80-401a-499c-938a-64610dea8443",
      "title": "Consulting"
    },
    "tags": ["urgent", "finance"],
    "total": 1500.0,
    "subtotal": 1400.0,
    "tax": 100.0,
    "tax_mode": "exclusive",
    "document_value_lines": [
      { "line_total": 1500.0, "line_subtotal": 1400.0, "line_tax": 100.0, "quantity": 2.0, "unit_price": 700.0 }
    ],
    "payment_method": {
      "id": "5c1591f6-1424-4f0d-bae6-0ad1492f8283",
      "name": "Credit Card",
      "type": "card"
    },
    "created_at": "2026-07-16T12:30:00Z",
    "updated_at": "2026-07-16T12:34:00Z"
  }
}

Notes on specific fields:

• event is created, updated, or deleted; entity is always document today.
• primary_category is one of expense, income, bank_statement, or document.
• For expenses and income, the payload includes the money fields shown above (total, subtotal, tax, line items) and, when a currency conversion applies, a currency_conversion block with the rate and converted amounts.
• Each line item also includes quantity and unit_price (display-only per-line metadata). Both are always present as numbers; when a per-line value was not captured they fall back to their defaults (quantity is 1, unit_price is 0).
• Documents also carry their AI Field values, integration publish status, and other metadata.
• If a file was blocked by malware scanning, its malware_blocked field is true and its download URLs are empty.
• In deleted events (and in the rare case where the document no longer exists when the webhook is sent), the payload contains document_id instead of the full document object.

Monitoring deliveries with the event log

Next to the webhook settings you'll find the Event log, which lists every webhook event with its queue time, event type, the document it concerns, delivery status, sent time, and the HTTP response code your endpoint returned.

From the log you can also re-send events:

• Send now delivers a queued event immediately instead of waiting for the batching window.
• Restart re-sends an event that already completed or failed. Failed deliveries are not retried automatically, so if your endpoint was down, use the event log to restart the missed events once it's back up. When restarting an already-successful event, make sure your automation can handle receiving the same event twice.

Using webhooks with Zapier or Make

You don't need to run your own server to use webhooks. Both Zapier and Make can receive them directly:

• In Zapier, create a Zap that starts with the Webhooks by Zapier trigger ("Catch Hook") and paste the generated URL into SparkReceipt as your webhook URL.
• In Make, add a Webhooks → Custom webhook module to a scenario and use its address the same way.

From there you can map the document fields to thousands of other apps — spreadsheets, cloud storage, accounting tools, or chat notifications.