Webhooks

Webhooks let Timefold notify your application in near real-time when a dataset reaches a terminal status. This page explains how to configure and monitor webhooks in the platform UI.

See Webhooks for when webhooks trigger and the statuses that cause them.

Configuring a webhook

To receive near real-time updates when dataset operations finish:

Log into Timefold Platform and click on the dropdown at the top right next to your username.
Click on Manage tenant.
In the menu on the left hand side click Webhooks to access the webhooks configured for your tenant.
Click Add Webhook to create a new webhook.
Enter the URL to receive event updates from your tenant.
Accept the generated name or provide a name for the webhook.

Optionally, you can define http-headers that Timefold will send along with the webhook, for instance, to pass on an Authorization header.

Enable or disable the webhook with the toggle.

Use secrets to inject sensitive values in configurations.

Logs

Timefold Platform stores logs for webhook activity that records the following information:

Timestamp
Duration (since Platform version v0.60)
Status
Model name
Model version
Dataset ID
Message

Click on a row to see full details, and for the option to retry sending a webhook notification.

Logs are kept for a maximum of 30 days.

To access the logs for a webhook, navigate to Manage tenant, Webhooks, and select the webhook.

Webhook payload

Here is an example payload that will be sent to the webhook when a dataset has completed:

{
  "id": "<the-id-of-the-dataset>",
  "name": "<name of the dataset>",
  "model": "field-service-routing",
  "modelVersion": "v1",
  "tags": [],
  "status": "SOLVING_COMPLETED",
  "runLink": "https://...", // Link to the API where you can fetch details about the dataset itself,
  "outputLink": "https://..." // Link to the API where you can fetch the dataset's output
}

Retry strategy

Our platform expects the webhook URL to return HTTP Status Code 200. If the response code is different, we will try again 10 seconds later. We will retry up to 10 times.

After 10 failed retries, we will notify the tenant administrators by email and include a link to the logs in the platform for the failed webhook. Email notifications are limited to one every 2 hours. No notification is sent if the webhook starts responding with the correct response code.

Timeouts

Timefold applies a 5-second timeout when delivering webhooks. This is consistent with industry standards.

There are two distinct timeout types, each handled differently:

Connect timeout: the connection could not be established. These are retried using the standard retry strategy above.
Read timeout: the connection was accepted but no response was received in time. These are not retried, to avoid delivering the same webhook event more than once.

Timefold does not use the webhook response body; only the HTTP status code matters. When a webhook arrives, your endpoint should put the event in a queue and return HTTP 200 immediately. The actual work, such as fetching the result, re-optimizing, or saving to storage, should be managed by a background worker that consumes from that queue. If your endpoint does heavy work during the webhook call itself, it will be vulnerable to timeouts regardless of how long the timeout window is. Increasing the timeout just shifts the problem.

HMAC authorization

Why HMAC authorization?

HMAC (Hash-based Message Authentication Code) authorization is used to verify that a webhook request actually comes from the Timefold Cloud Platform and hasn’t been tampered with in transit.

Security: Ensures that only requests signed with your secret HMAC key are accepted.
Integrity: Confirms that the webhook payload or request path hasn’t been altered.
Replay protection: By including a timestamp in the signed request, you can detect and reject replayed requests.

Using HMAC verification adds an extra layer of trust to your webhook integrations, and is especially useful when the webhook triggers important actions in your system.

How to enable HMAC

When setting up a webhook in the Timefold Platform, go to the Authorization dropdown in the webhook’s settings.
Select HMAC (default is None).
Provide a HMAC key. This secret key will be used to sign all webhook requests.

Once enabled, Timefold will automatically include the following headers in each webhook request:

X-Timefold-Signature: the HMAC signature of the request.
X-Timefold-Timestamp: the time of the request, in ISO-8601 format yyyy-mm-ddThh:mm:ssZ.

We use HMAC_SHA_256 as the hashing algorithm and the values are base64 encoded.

Signature content options

By default, the HMAC signature is calculated over the webhook Body (= payload). You can also choose Path in the HMAC Method dropdown, if you want the signature to be based on the webhook URL path instead.

Custom headers

The HMAC signature: {hmac_signature} and the time: {hmac_timestamp} can also be used as variables when configuring custom headers.

This allows you to:

Send the signature and timestamp under different header names.
Add prefixes or postfixes to the values of the headers.

Example configurations

Default HMAC setup

Webhook settings

URL: http://example.org/path-to-receiving-endpoint
Authorization: HMAC
HMAC method: Body
Headers: none

Sample request sent by Timefold

POST /path-to-receiving-endpoint HTTP/1.1
Host: example.org
Content-Type: application/json
X-Timefold-Signature: f2Ak8ODZo7...
X-Timefold-Timestamp: 2025-09-26T10:28:16Z

{"id":"8dbdce26-8b9a-45a2-9cb5-0a3dc2fc2cc7", "parentId": [...]}

Verification pseudocode

signature_header = request.headers["X-Timefold-Signature"]
timestamp_header = request.headers["X-Timefold-Timestamp"]

content = request.body  // raw JSON string

expected_signature = base64encode(HMAC_SHA_256(secret_key, content))

if !secure_compare(signature_header, expected_signature):
    reject_request("Invalid signature")

if abs(current_time - timestamp_header) > allowed_window:
    reject_request("Stale request")

HMAC setup using method "Path" and custom headers

Webhook settings

URL: http://example.org/path-to-receiving-endpoint
Authorization: HMAC
HMAC method: Path
Headers:
- X-My-Custom-Signature: MYPREFIX:{hmac_signature}
- X-My-Custom-Timestamp: {hmac_timestamp}

Sample request sent by Timefold

POST /path-to-receiving-endpoint HTTP/1.1
Host: example.org
Content-Type: application/json
X-My-Custom-Signature: MYPREFIX:Qk1fpcu1oL...
X-My-Custom-Timestamp: 2025-09-26T10:28:16Z

{"id":"8dbdce26-8b9a-45a2-9cb5-0a3dc2fc2cc7", "parentId": [...]}

Verification pseudocode

signature_header = request.headers["X-My-Custom-Signature"]
timestamp_header = request.headers["X-My-Custom-Timestamp"]

// remove prefix before verification
raw_signature = signature_header.remove_prefix("MYPREFIX:")

content = "POST" + "+" + request.path + "+" + timestamp_header

expected_signature = base64encode(HMAC_SHA_256(secret_key, content))

if !secure_compare(raw_signature, expected_signature):
    reject_request("Invalid signature")

if abs(current_time - timestamp_header) > allowed_window:
    reject_request("Stale request")

Firewall and IP allowlisting

Timefold webhooks are delivered from our cloud infrastructure and may originate from IP addresses that can change over time. We do not publish or guarantee a fixed IP address or IP range for webhook delivery.

If you need to restrict incoming traffic, we strongly recommend validating the HMAC signature (X-Timefold-Signature and X-Timefold-Timestamp headers) as the primary mechanism to verify that a request originates from the Timefold Platform. Several modern firewalls also support performing HMAC verification themselves, allowing you to enforce signature validation before traffic reaches internal systems.

In more restricted network setups where the firewall cannot perform HMAC verification, a common pattern is:

Expose a small, controlled service with a static public IP address.
Allowlist that static IP in your firewall.
Let that service receive the webhook, perform the HMAC verification, and then forward only trusted requests to internal systems.