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

Creating a webhook requires the read scope of the collection you subscribe to, in addition to connector-protimeapi-webhooks.write. The required scope is not always named after the collection – paid-presences uses the calculated totals scope.

Webhook properties

Status values

Webhook expiration and renewal

Each webhook has a validity period exposed via the validUntil property (ISO 8601 timestamp), set when the webhook is created. There is no dedicated “refresh” or “touch” endpoint, but the validity period can be extended by re-POSTing to /webhooks with the same destinationUrl and collectionName (see Renewing a webhook). This works whether the existing webhook is still Enabled or has already become Disabled.

When a webhook becomes Disabled

A webhook transitions to the Disabled state when either:

• validUntil is reached, or
• all retries are exhausted after repeated delivery failures (see Automatic retries).

Once Disabled, event delivery stops and any events that were still being retried are purged.

Renewing a webhook

A webhook is renewed by POSTing to /webhooks again with the same destinationUrl and collectionName as the original subscription. The system updates the existing subscription rather than creating a duplicate, and the response contains:

• A new private webhook key that replaces the old one. Subsequent HMAC validations must use the new key; the previous key immediately stops matching inbound signatures.
• A new validUntil value, extending the validity period.

The existing subscription is updated in place, so the webhook keeps the same id across renewals. The destinationUrl + collectionName pair is what identifies the subscription to renew.

Renewal behaves differently depending on the current status:

• Enabled (proactive renewal). Re-POSTing before validUntil is reached pushes the expiration forward in place. Event delivery is never interrupted, so no re-sync is needed. The external references in the renewal request must match those of the existing webhook; otherwise the request is rejected. External references cannot be changed this way – delete and recreate the webhook instead.
• Disabled (recovery). Re-POSTing re-enables a webhook that expired or was disabled after repeated delivery failures. Because events were dropped while it was disabled, a re-sync is required first (see below).

Mandatory pre-renewal re-sync (Disabled only)

Events that occurred while the webhook was disabled are not replayed when the subscription is re-enabled. The renewed webhook only delivers events that occur after the renewal call.

Before renewing a Disabled webhook, perform a full data re-synchronization using the collection’s GET list endpoints (or a fresh delta initial request). This fills the gap between the last successful delivery and the renewal. See Handle webhook expiration for the step-by-step procedure.

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

Scope: connector-protimeapi-webhooks.write and the read scope of the collection named in collectionName. See Supported collections for the scope each collection requires.

connector-protimeapi-all.read satisfies the collection requirement for any collection. connector-protimeapi-all.write covers connector-protimeapi-webhooks.write, but does not cover the read requirement – a token holding only write scopes cannot create a webhook. Both general scopes are only requestable by credentials entitled to them.

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).

A token missing either scope receives 401 Unauthorized naming the scope that is absent.

Retrieve a list of webhooks

Scope: connector-protimeapi-webhooks.read

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

Scope: connector-protimeapi-webhooks.read

Delete a webhook

Scope: connector-protimeapi-webhooks.write

Performs a soft delete. Returns 204 No Content on success. 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