Webhooks

Webhooks let your server react to document processing events in real time — no polling required. When a document is extracted or fails, DocsToSheets sends an HTTP POST to each matching endpoint you configure.

Setting up a webhook

1. Open Settings → Developer (paid plans only).
2. Scroll to the Webhooks section and enter an endpoint URL.
3. Select which events to send (you can pick one or both).
4. Optionally choose a Mailbox Filter — events from all other mailboxes will not be sent.
5. Click Add Webhook.
6. Copy the signing secret immediately — it is shown only once. Store it as a secret environment variable in your server.

Verifying signatures

Every request includes an X-Webhook-Signature header you can use to confirm the payload came from DocsToSheets and was not tampered with.

X-Webhook-Signature: sha256=<hex-encoded HMAC-SHA256>

The signature is computed over the raw request body using your signing secret as the key. Verify it before processing the payload.

Node.js (built-in crypto)

import crypto from 'node:crypto';

function isValidSignature(rawBody, sigHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sigHeader), Buffer.from(expected));
}

Python (hmac stdlib)

import hmac, hashlib

def is_valid_signature(raw_body: bytes, sig_header: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(sig_header, expected)

C# (.NET)

using System.Security.Cryptography;
using System.Text;

bool IsValidSignature(string rawBody, string sigHeader, string secret)
{
    var key = Encoding.UTF8.GetBytes(secret);
    var body = Encoding.UTF8.GetBytes(rawBody);
    var hash = HMACSHA256.HashData(key, body);
    var expected = "sha256=" + Convert.ToHexString(hash).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(sigHeader),
        Encoding.UTF8.GetBytes(expected));
}

Always use a constant-time comparison to prevent timing attacks.

Event reference

document.extracted

Fired when a document is successfully processed and an extraction is saved.

{
  "event": "document.extracted",
  "webhookId": "abc123",
  "timestamp": "2026-06-11T12:34:56.789Z",
  "data": {
    "documentId": "d_...",
    "mailboxId": "m_...",
    "accountId": "a_...",
    "extractionId": "e_...",
    "splitValue": "Year_2025",
    "validationStatus": "Valid",
    "documentType": "Email"
  }
}

Field	Description
documentId	ID of the processed document
mailboxId	Mailbox the document belongs to
accountId	Your workspace account ID
extractionId	ID of the resulting extraction record
splitValue	Split-key path (empty string if no splits are configured)
validationStatus	Valid, Warning, or Invalid
documentType	Email, Pdf, Image, or Manual

document.failed

Fired when a document fails processing after all retry attempts are exhausted.

{
  "event": "document.failed",
  "webhookId": "abc123",
  "timestamp": "2026-06-11T12:35:00.000Z",
  "data": {
    "documentId": "d_...",
    "mailboxId": "m_...",
    "accountId": "a_...",
    "failureReason": "Unsupported file format",
    "documentType": "Email"
  }
}

Field	Description
documentId	ID of the failed document
failureReason	Human-readable description of why processing failed

Delivery behaviour

• Requests use HTTP POST with Content-Type: application/json.
• DocsToSheets attempts delivery up to 3 times with exponential back-off (1 s, 3 s, 9 s) on non-2xx responses or network errors.
• Your endpoint should respond with a 2xx status within a reasonable timeout. Slow endpoints may be retried if the connection times out.
• Delivery is fire-and-forget — there is no delivery log in the UI.

Zapier integration

Use the Webhooks by Zapier trigger (catch hook) to connect DocsToSheets events to any Zapier workflow:

1. In Zapier, create a new Zap with Webhooks by Zapier → Catch Hook as the trigger.
2. Copy the generated Zapier hook URL.
3. Create a DocsToSheets webhook with that URL (select document.extracted for most automation use cases).
4. Send a test document through the mailbox to trigger a sample payload in Zapier.
5. Build your Zap actions using the extracted data fields.

For signature verification in Zapier, use a Code by Zapier step before your action steps and verify the X-Webhook-Signature header using the Python or Node.js examples above.