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#
1.
Event Occurs: An action happens in Commusoft (e.g., a user updates a job status).
2.
Notification Sent: Commusoft sends an HTTPS POST request to a URL you specify.
3.
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.{
"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.1.
Navigate to Settings > Private application
3.
Under the Webhooks tab, click Add Endpoint.
4.
Enter your Destination URL (must be HTTPS).
5.
Select the Events you wish to listen for.
6.
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=signatureVerification Steps:#
1.
Extract Header Values: Extract the Unix timestamp t and the signature v1 from the X-Commusoft-Signature header.
2.
Prepare the Base String: Create a "signature base string" by concatenating the timestamp t, a period ., and the raw JSON request body.
3.
Calculate the Hash: Compute an HMAC-SHA256 hash using your Signing Secret as the key and the base string as the message.
4.
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.
5.
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. Modified at 2026-05-06 11:43:58
