Receiving notifications

Now that webhooks have been created and saved in SuperOffice, notifications can be sent out when an event occurs. A webhook notification is referred to as a WebhookPayload, and contains the following properties:

Property Name	Description
EventId	A GUID that uniquely identifies this event.
Timestamp	The datetime when the event occurred.
Event	The name of the event.
Entity	The type of entity that was affected, activity, associate, contact, person
PrimaryKey	The entity identity that was affected
Changes	An array of fields that are connected to the change.
FieldValues	List of key-value pairs that contain non-sensitive data from the data record
ContextIdentifier	Customer ID for Online users: “Cust1234”. Not used for On-site installations.
ChangedByAssociateId	Associate ID of the user that triggered the event.
WebhookName	The given name of the webhook.

A webhook payload for the event contact.changed is send as the following JSON message:

UserAgent: NetServer-Webhook/8.2.123.456X-SuperOffice-Signature: abcXyz123==X-SuperOffice-Event: contact.changedX-SuperOffice-EventId: 88f91933-edce-4c1a-8ded-ade8e2f72434{
    "EventId":"88f91933-edce-4c1a-8ded-ade8e2f72434",
    "Timestamp":"2025-05-14T10:48:07.8912039Z",
    "Changes":["contact_id","updated_associate_id","soundEx","updated","name"],
    "Event":"contact.changed",
    "PrimaryKey":18,
    "Entity":"contact",
    "ContextIdentifier":"Cust54321",
    "ChangedByAssociateId":5,
    "WebhookName":"Tonys Contact Handler",
    "FieldValues": {
        "activeInterests": 0,
        "associate_id": 12,
        "business_idx": 2,
        "category_idx": 4,
        "country_id": 826,
        "deleted": 0,
        "DeletedDate": "0001-01-01T00:00:00",
        "registered": "2020-02-16T17:50:17",
        "registered_associate_id": 5,
        "source": 0,
        "updated": "2025-05-14T10:48:07.8912039+02:00",
        "userdef2_id": 0,
        "userdef_id": 22
    }
}

Notifications are sent out in a fire-and-forget fashion and do not expect a response to these POST requests. There is no way to prevent changes or interrupt the normal workflow of SuperOffice.

🛈 Note

The event name, event ID, and signature are sent as HTTP headers, to help the recipient route and filter the notification without having to parse the body.

Changes field names

Fields names that appear in a notification Changes property are the names of the fields as they appear in the database.

Entity name	Field source
Activity	Appointment table
Associate	Associate table
Contact	Contact table
Chat	ChatSession table
Document	Document table
Person	Person table
Project	Project table
ProjectMember	ProjectMember table
Quote	Quote table
Sale	Sale table
SaleStakeholder	SaleStakeholder table
Ticket	Ticket table

WebhookPayload headers

Header name	Description
X-SuperOffice-Event	The event name (contact.created, project.changed)
X-SuperOffice-EventId	A GUID that uniquely identifies this event.
X-SuperOffice-Retry	The number of retries this webhook has been tried to be sent.
X-SuperOffice-Signature	The hash/base64 encoded secret.

Error Handling for Webhooks

There are three attempts to send a webhook payload during a single cycle. If the first one fails, the next attempt is delayed by 1 second. If the second attempt fails, the third attempt is delayed by 4 seconds. If the third attempt fails, it is removed from this cycle and sent to the back of the queue. All active webhook payloads are given a total of 9 consecutive attempts before the state is changed to TooManyErrors (3).

If the HTTP request fails to receive a 200 response for three attempts, the event associated with those attempts is discarded, and the webhook’s consecutive_errors count is incremented. The next attempt made will feature a new EventID.

Email Notification on Error

In the event that the EmailErrors property is set, when a webhook state is set to TooManyErrors, an automatic email will be dispatched to the specified email address. This email will detail the error, the associated EventID, Name and more details.

The EventID remains consistent for each attempt, facilitating accurate tracking and management of webhook events. However, if there are three consecutive failed attempts, the event is discarded, and the next attempt will be associated with a new EventID.

Following TooManyErrors status, it is the responsibility of the receiver to manage the webhook state. The receiver can reset the state to Active (1) to resume the sending of webhook payloads. The EmailErrors notification system is designed to promptly inform the receiver of any critical issues that might prevent successful data delivery.