Status Change Webhook

In SiteCapture you can configure a webhook which will send an HTTP request to a specific URL anytime your SiteCapture projects enter a particular workflow state.  This is particularly useful for integrations; for example: the transfer of data from SiteCapture to another system might be triggered when projects enter the COMPLETE workflow state.

Table of Contents:

• Creating A Webhook
• How It Works
• What fires the webhook
• Configuration
• Request format
• Payload
• Verifying the HMAC signature
• Delivery and retries
• When something goes wrong
• Validating a Webhook Request

Creating A Webhook

1. Under the gear icon, select App Integrations.

2. On the integrations page, select: SiteCapture Webhook on Project Status Event.

3. Click the Configure button, and then Next.

4. Enter the Webhook URL

4. It's possible to receive the webhook for ALL statuses, including those that don't have an associated workflow state. Click the button to the right (On). 

5. If you'd like to receive notifications only for specific workflow states, click the button to the left (Off). Click the “Add to Send the webhook for specific workflow states” button and then choose a workflow state.  Repeat this to include all desired workflow states.

6. If you would like to validate the incoming webhook requests, copy the “HMAC Shared Secret” for later.  (See below).

7. Click Finish.

8. If you need to reconfigure the webhook, pause the integration, or deactivate the integration you can do so after clicking on the "SiteCapture Webhook on Project Status Event". 

How It Works

This integration lets a customer receive a webhook from SiteCapture whenever a project changes status. SiteCapture POSTs a small, fixed JSON payload to a URL the customer provides, and signs the request body with HMAC-SHA-256 so the customer can verify it came from us.

What Fires the Webhook

The webhook fires when a SiteCapture project's status changes. Whether a given status change actually sends a webhook depends on the instance's filter configuration:

• Send for all workflow states (default) — every status change fires the webhook.
• Send for specific workflow states — only status changes that land in one of the selected states fire the webhook. Available states: NEW, ASSIGNED, ACCEPTED, DECLINED, CANCELLED, IN_REVIEW, COMPLETE, COMPLETE_REVIEWED, COMPLETE_OTHER, CLOSED.

Configuration

Each instance of the integration is configured with three values:

Setting	Required	Notes
Webhook URL	yes	The HTTPS endpoint SiteCapture will POST to.
HMAC Shared Secret	yes	Auto-generated on instance creation (16 random bytes, hex-encoded). Read-only in the UI. Share this with the customer so they can verify request signatures.
Webhook Filter	yes	Either "all workflow states" or a list of specific states to filter on.

Request format

Every webhook is a POST to the configured URL with:

• Content-Type: application/json
• Accept: application/json
• x-hmac-hash: <hex HMAC-SHA-256 of the request body>
• A JSON body with the payload below.

Payload

The payload structure is fixed (not configurable). It always contains exactly these fields:

{

  "project_id": 3057,

  "status": "Complete",

  "workflow_state": "COMPLETE",

  "api_key": "your_api_key",

  "event": "status_change",

  "template_key": "your_template_key"

}

Field	Type	Description
project_id	number	SiteCapture project ID.
status	string	Human-readable project status (e.g. "Complete", "Approved-Closed").
workflow_state	string	Machine workflow state — one of the values listed in the filter section above.
api_key	string	The customer's SiteCapture API key.
event	string	What triggered the webhook. Always "status_change".
template_key	string	The key of the project's template.

Verifying the HMAC Signature

The x-hmac-hash header is the HMAC-SHA-256 of the raw request body bytes, using the shared secret as the key, hex-encoded (lowercase).

To verify a webhook, the receiver should:

1. Read the raw request body bytes exactly as received.
2. Compute hex(HMAC_SHA256(shared_secret, raw_body_bytes)).
3. Compare the result to the x-hmac-hash header.

Only the request body is signed — no headers are included in the signature. The body is UTF-8 encoded JSON.

Important: verify against the raw bytes as received. Do not parse the JSON and re-serialize it before computing the HMAC — different JSON serializers produce different bytes (whitespace, field order, escaping), and the signature will not match.

Delivery and Retries

SiteCapture retries failed deliveries up to 10 times with exponential backoff. Any non-2xx response (or network error) counts as a failure and triggers a retry. The wait between attempts doubles each time (starting at ~100 ms), summing to roughly 1.5 to 2 minutes of total backoff across all 11 attempts, plus the time the requests themselves take. After all retries are exhausted, the delivery is logged as failed and no further attempts are made for that event.
 

The receiver should respond 2xx as soon as it has durably received the webhook, and do any slower processing asynchronously, to avoid being retried unnecessarily.

When Something Goes Wrong

• Webhook URL is unreachable or returns a non-2xx response: SiteCapture retries with exponential backoff up to 10 times (~1.5 to 2 minutes of total backoff), then gives up for that event.
• HMAC mismatch on the receiver: the most common cause is re-serializing the parsed JSON before computing the HMAC. Verify against the raw body bytes as received.
• Missing events: if a status change did not produce a webhook, check the instance's Webhook Filter — the new workflow state may not be in the selected list.

Validating a Webhook Request

There are two pieces of information sent in each webhook request to help validate that the request has been sent by SiteCapture and not some other party:

1. Your API key is included in the request body
2. An encoding of the request body is included in an HTTP header called  x-hmac-hash

With (1), you can validate that the incoming key matches your SiteCapture API key.

With (2), you can calculate an HMAC signature using the incoming request body (JSON) and the “HMAC shared secret” that is visible in the Webhook configuration screen, as described above.  This can be done programmatically or using a tool such as this one:  

https://emn178.github.io/online-tools/sha256.html