Skip to main content

Webhooks - General Usage

What is a Webhook? Think of a Webhook as a instant text message notification sent between apps. Fieldwork automatically alerts your other system the second something happens.

Written by Beau O'Hara


​Plan Availability: Webhooks are included in Pro and Enterprise plans. If you do not see Webhooks under Settings > Company Settings, your account plan does not currently include this add-on.
​

1. Core Concepts

To set up webhooks, you only need to understand three core terms:

Term

What It Means in Plain English

Endpoint

The web address (URL) of your receiving application. You can set up to 5 endpoints per account. Each has its own name, switch (on/off), and error tracker.

Subscription

A rule that tells Fieldwork: "When [THIS HAPPENS] to [THIS RESOURCE], send a alert to [THESE ENDPOINTS]."

Signing Secret

A unique security key for your account. It acts like a digital signature to prove that incoming messages actually came from Fieldwork and not an imposter.

Flexible Design: You can send alerts from one subscription to multiple endpoints (e.g., send invoice updates to both your CRM and your warehouse), or have one endpoint receive alerts from multiple subscriptions.


2. Step-by-Step Setup Guide

Follow these steps inside Fieldwork under Settings > Company Settings > Webhooks.

Step 1: Set Up Your Endpoint

  1. Go to the Endpoints tab.

  2. Copy the Signing Secret shown at the top. You will paste this key into your receiver app for security.

  3. Click Add Endpoint and fill in:

    1. Name: A clear label (e.g., "Zapier CRM Connector" or "Warehouse Integration"). Must be unique.

    2. Name: A clear label (e.g., "Zapier CRM Connector" or "Warehouse Integration"). Must be unique.

    3. URL: The secure web address of your receiver (must begin with https://).

    4. Active: Leave checked to turn it on immediately (uncheck if you want to pause notifications without deleting it).

    5. Add to existing subscriptions: Leave checked if you want this new endpoint to receive all currently active webhooks.

    6. Click Save Endpoints.

Step 2: Create Subscriptions

Note: The Subscriptions tab becomes available after saving your first endpoint.

  1. Go to the Subscriptions tab and click Add Subscription.

  2. Select a Resource (e.g., Customer, Work Order, Invoice). Note: Each resource can only have one row in subscriptions.

  3. Select the Actions you want to hear about (e.g., create, update, destroy).

  4. Select which Endpoints should receive these alerts.

  5. Click Save Subscriptions.

Step 3: Test Your Setup

  1. On any subscription row, click Show Example to preview the exact data format.

  2. Click Make Test Request inside the pop-up window to send a test message to your selected endpoints.

  3. Note: Test requests carry a special header (X-Fieldwork-Test: true) and won't affect your error counters or actual records.

3. What Events Can You Subscribe To?

Fieldwork can alert you about 5 main types of records. You can choose specific actions for each:

Resource (UI Name)

Technical Wire Name

Available Actions

Work Order

work_order

create, update, destroy, status_change, date_change

Work Order Series

work_order_series

create, update, destroy

Customer

customer

create, update, destroy, status_change

Invoice

invoice

create, update, destroy, status_change, date_change

Payment

payment

create, update, destroy, date_change

Understanding What Each Action Means

  • create: A brand new record was created (or a previously deleted record was restored).

  • update: Any change was made to the record.

  • destroy: The record was deleted. Contains the last known details before deletion.

  • status_change: A specialized update triggered only when status changes (e.g., Invoice paid, Customer placed on financial hold, Work Order status changes).

  • date_change: A specialized update triggered only when dates change (e.g., Work Order start time, Invoice due date, Payment date).

Pro-Tip on Actions: update includes everything. If you check update alongside status_change or date_change, Fieldwork automatically removes the narrower ones when saving. Choose update for "tell me everything," or pick narrow actions for "only tell me when specific key fields change."
​

4. How Delivery Works (Crucial Rules to Keep in Mind)

  • Batched, Not Instantaneous: Fieldwork collects changes over short periods (a few minutes) and dispatches them together. One delivery message can carry up to 50 events. Always make sure your code handles lists/arrays of records.

  • Latest State Only: If a record is edited 5 times within a few minutes, Fieldwork sends 1 event containing the final updated state. Webhooks do not provide a step-by-step history of every single micro-edit.

  • Grouped by Event Type: Creating an invoice and updating an invoice will arrive in separate requests, even if they happened at the same time.

  • At-Least-Once Delivery: Sometimes a system retry means you receive the exact same webhook message twice. Make sure your receiving system handles duplicates cleanly.

  • No Backfill: Webhooks are only recorded when active. If your endpoint is paused or turned off, Fieldwork will not queue or resend missed changes once you turn it back on.

5. Technical Verification & Security (For Developers)

Every webhook HTTP request contains a signature header (X-Fieldwork-Signature) formatted like: t=1755259200,v1=6a9e...c41d.

To verify the message is genuine:

  1. Read the raw JSON request body bytes before parsing.

  2. Construct the payload string: "{timestamp}.{raw_body}".

  3. Compute an HMAC-SHA256 signature using your account's Signing Secret and compare it against the v1 value in constant time.

  4. Reject any request where the timestamp (t) is older than your tolerance limit (e.g., 5 minutes) to protect against replay attacks.

Using Zapier or No-Code Tools?

Tools like Zapier do not expose raw HTTP headers for signature validation. In these cases, protect your workflow by keeping your endpoint URL strictly confidential.
​

6. Secret Rotation & Error Handling

Rotating Your Signing Secret Safely

  1. Click Reset on the Endpoints tab to generate a new secret.

  2. Copy the new secret and update your receiving apps.

  3. Note: Fieldwork temporarily honors both the old and new key during a rotation. However, doing a second reset immediately invalidates the oldest key.

Retries & Auto-Disabling

  • Timeout: Fieldwork waits 10 seconds for a response from your server.

  • Success: Any HTTP 2xx code counts as successful.

  • Retries: Errors like 5xx, 408, 429, or connection timeouts trigger up to 5 retry attempts with increasing delays.

  • Auto-Disable Safety Trigger: If an endpoint fails 25 consecutive times, Fieldwork disables it automatically to protect system resources. To fix it: repair your receiver app, then open the Endpoints tab and click Save to clear the counter and re-enable it.

7. Troubleshooting Quick Reference

Problem / Symptom

What it Means & How to Fix It

"Webhooks" option is missing in settings

Your Fieldwork account is not on a Pro or Enterprise plan. Upgrade your plan to unlock webhooks.

Not receiving any webhook deliveries

Check if: (1) An active subscription exists for that event, (2) The endpoint is switched on, or (3) The endpoint was auto-disabled due to 25 failed attempts.

Signature verification always fails

Ensure your app is checking raw unparsed request bytes. JSON parsing changes spacing and formatting, breaking the digital signature match.

Webhooks suddenly stopped working after a server update

Your receiver likely threw errors during deploy, causing Fieldwork to hit the 25-failure limit. Fix your receiver, then go to the Endpoints tab and click Save to reactivate it.

Receiving duplicate alerts for the same change

This is normal for webhooks ("at-least-once" delivery). Design your receiver to ignore duplicate Delivery IDs or Record IDs.

Related Articles
Did this answer your question?