Webhooks

With webhooks, Timefold sends an HTTP POST to an endpoint on your server when a dataset reaches a terminal status. This is a push model: your application doesn’t need to check for results; Timefold calls you.

Use webhooks in production because:

  • Your application doesn’t consume resources polling for results.

  • Timefold retries delivery automatically if your endpoint is temporarily unavailable.

  • The webhook payload includes the dataset ID and a direct link to the output, so your handler only needs to fetch the solution.

The architectural requirement is that your webhook endpoint must be reachable from Timefold’s infrastructure. This means it needs a public URL (or a URL reachable from Timefold’s network). If your application runs behind a firewall, you’ll need to expose a webhook receiver endpoint and validate incoming requests using HMAC signatures.

Don’t do heavy work in your webhook handler. Receive the event, put it on an internal queue, return HTTP 200 immediately, and process the result asynchronously in a background worker. This keeps your handler resilient to timeouts regardless of how long your downstream processing takes.

See Webhooks for how to configure a webhook in the platform UI, view webhook activity logs, the webhook payload format, retry behavior, and HMAC signing details.

When webhooks trigger

Webhooks trigger when a dataset reaches the following statuses:

  • Dataset computed

  • Dataset invalid

  • Solving completed (This includes when a dataset solve operation is cancelled.)

  • Solving incomplete

  • Solving failed

Read more about statuses: Dataset lifecycle.

If the webhook is always triggered, for each event we will send a POST call to the specified URL.

In the configuration UI you can specify (optional) filters to only receive webhooks in certain cases:

  • Only when datasets reach certain statuses.

  • Only for datasets with a name that matches a specific regular expression.

  • Only for datasets that have the specified tags.