Webhooks

Webhooks allow your application to receive real-time notifications from Commusoft. Instead of polling our API for changes, Commusoft will "push" data to your server as soon as an event occurs—such as a job being updated or a new property being created.

How Webhooks Work

Event Occurs: An action happens in Commusoft (e.g., a user updates a job status).

Notification Sent: Commusoft sends an HTTPS POST request to a URL you specify.

Your Server Processes: Your server receives the notification and performs an action.

Event Objects & Types

We currently support webhooks for the following primary objects. You can subscribe to specific actions for each:

Event type	Properties
Properties	created, updated, deleted
Opportunities	created, updated, deleted
Jobs	created, updated, deleted

Payload Structure

Commusoft uses a Thin Payload strategy. To ensure data security and accuracy, we send the unique ID of the resource rather than the full data object. This ensures you always fetch the most up-to-date information via the API.

Example Payload

{
   "timestamp": "2026-04-29T10:15:30Z",
   "applicationID": "a987654321",
   "clientID":"16198",
   "eventID": "789abc",
   "version": "2",
   "object": "jobs",
   "eventType": "job.updated",
   "id": 101,
   "links": {
      "self": "https://app.commusoft.co.uk/api/v2/jobs/101"
   }
}

Registration & Setup

You can manage your webhook subscriptions either inside the Private application settings or via an API.

Navigate to Settings > Private application

Select your application.

Under the Webhooks tab, click Add Endpoint.

Enter your Destination URL (must be HTTPS).

Select the Events you wish to listen for.

Save the generated Signing Secret (you will need this for security verification).

Security: Verifying Signatures

To ensure that a webhook was actually sent by Commusoft and not a third party, we sign every request with an HMAC-SHA256 signature.

Every request includes an X-Commusoft-Signature header.

Header Format: t=timestamp,v1=signature

Verification Steps:

Extract Header Values: Extract the Unix timestamp t and the signature v1 from the X-Commusoft-Signature header.

Prepare the Base String: Create a "signature base string" by concatenating the timestamp t, a period ., and the raw JSON request body.

Example: 1714385730.{"applicationID":"a987654321",...}

Calculate the Hash: Compute an HMAC-SHA256 hash using your Signing Secret as the key and the base string as the message.

Compare Results: Convert the resulting hash to a hexadecimal string. Compare this string with the v1 value from the header. If they match, the request is authentic.

Replay Protection: Always verify that the timestamp t is within a reasonable tolerance (e.g., 5 minutes) of your current server time to prevent replay attacks.

Reliability & Retries

If your server is down or returns an error (anything other than a 2xx status code), Commusoft will attempt to redeliver the notification.

Retry Policy: We use exponential backoff, retrying up to 10 times over 24 hours.

Automatic Disabling: If an endpoint fails consistently for more than 48 hours, it will be automatically "Paused," and an email will be sent to the application administrator. Any data which would have been sent when the webhook was paused will not be retried. Once you've unpaused the webhook (either via the Private applications interface or via an API) data will resume being sent.

Idempotency: Because of retries, your server may occasionally receive the same event twice. You should use the eventID to ensure your logic is idempotent (i.e., processing the same event twice doesn't cause duplicate actions).

Best Practices

Return a 2xx quickly: Respond to the webhook as soon as you receive it. Perform heavy processing or third-party API calls in a background task on your end.

HTTPS only: We only deliver webhooks to secure HTTPS endpoints.

Avoid Echo Loops: If your application reacts to a webhook by making a POST request back to Commusoft, ensure you aren't creating an infinite loop. Check the applicationID in the payload to ignore actions triggered by your own app.

How Webhooks Work#

Event Objects & Types#

Payload Structure#

Registration & Setup#

Security: Verifying Signatures#

Verification Steps:#

Reliability & Retries#

Best Practices#