Webhooks

This page documents the webhook specification for the Protime API, including supported collections, properties, HMAC signature format, automatic retry intervals, expiration behavior, and management endpoints.

Supported collections

The following collections support webhooks:

Webhook properties

Status values

Webhook expiration

• Each webhook has a limited validity period, indicated by the validUntil property.
• When a webhook expires or is disabled, a full reinitialization is required: perform a complete initial sync, then create a new webhook.
• Reusing an expired or disabled webhook is not supported.

changeVersion field

Each object in a webhook event includes a changeVersion field. This field supports string comparison for determining relative ordering. If a newly received object has a changeVersion older than a previously received object with the same identifier, the newer receipt can be ignored.

Some actions in the Protime environment can trigger multiple webhook events due to automatic calculations. The changeVersion field is the mechanism for handling duplicates and ordering.

Event payload format

Each webhook event is delivered as a JSON object with two fields:

Example:

{
    "changeType": "InsertOrUpdate",
    "data": {
        "id": "d4f7a5c1-0e82-4b3a-9c6f-1a2b3c4d5e6f",
        "changeVersion": "00000000000000012345"
    }
}

The data object contains all fields of the affected resource, matching the shape returned by the corresponding collection GET endpoint.

The data object includes a changeVersion field that supports ordering and deduplication (see changeVersion field).

HMAC-SHA256 signature

Every webhook request includes an HMAC signature in the Authorization header:

Authorization: HMAC-SHA256 {signature}

The signature is generated using:

• Algorithm: HMAC-SHA256
• Key: The private webhook key returned when the webhook is created
• Input: The exact JSON request body
• Encoding: The result is Base64-encoded

The Authorization header always indicates the authentication scheme used (HMAC-SHA256), allowing future scheme upgrades.

Validation example (C#)

private async Task<bool> ProtimeAuthHeaderIsValid(AuthenticationHeaderValue protimeAuthHeaderValue)
{
    if (protimeAuthHeaderValue.Scheme == "HMAC-SHA256")
    {
        var requestBody = await GetJsonRequestBody();
        const string webhookKey = "privateWebhookKey";

        using var hmacSha256 = new HMACSHA256(Encoding.UTF8.GetBytes(webhookKey));
        var bytes = Encoding.UTF8.GetBytes(requestBody);
        var hash = hmacSha256.ComputeHash(bytes);
        var calculatedHmacSignature = Convert.ToBase64String(hash);

        return protimeAuthHeaderValue.Parameter == calculatedHmacSignature;
    }

    return false;
}

Automatic retries

Webhooks contain a built-in retry mechanism. The default retry intervals are:

The total retry window is up to 72 hours.

If the webhook consumer fails to respond with a success status code after all retries, automatic retries stop and the webhook is disabled. All events still in a retry state at that moment are purged.

Occasional duplicate delivery is possible. Every event includes a changeVersion that enables idempotent processing.

Management endpoints

Create a webhook

Request body:

{
    "destinationUrl": "https://www.fictional-customer.com/protime/clockings",
    "collectionName": "{collectionName}"
}

On success, the response includes:

• Status: 201 Created
• Location header: /connector/protimeapi/api/v1/webhooks/{id}
• Response body: Contains the private webhook key (store it for HMAC validation).

Retrieve a list of webhooks

Response:

{
    "value": [
        {
            "id": "a7d853ea-89eb-4735-83d1-b891c6fde398",
            "validUntil": "2025-03-31T12:30:00+02:00",
            "status": "Enabled",
            "destinationUrl": "https://www.fictional-customer.com/protime/clockings",
            "collectionName": "clockings"
        }
    ]
}

Filters

Retrieve a webhook by ID

Delete a webhook

Performs a soft delete. The webhook remains queryable via debugging endpoints after deletion.

External references with webhooks

Predefined external references

{
    "destinationUrl": "https://www.fictional-customer.com/protime/clockings",
    "collectionName": "clockings"
}

Custom external references

{
    "destinationUrl": "https://www.fictional-customer.com/protime/clockings",
    "collectionName": "clockings"
}

See also

• How to set up webhooks
• Webhook lifecycle