Creating Task Handlers

This page describes how to create a task handler, the code that handles a push task. App Engine executes tasks by sending HTTP requests to your application. You must provide a request handler to execute your task code. The mapping from the request URL to the code is declared in your service's web.xml, just like any other request handler. Because you control how to map task requests to a handler, you're free to organize your task handlers. If your application processes many different kinds of tasks, you can add all the handlers to a single service, or you can distribute them among multiple services.

Writing a push task request handler

The Task Queue service creates an HTTP header and sends it to an instance of the worker service specified by the task's target. The task's URL is appended to the request's URL, so the worker can select the appropriate handler for the task. App Engine sends Task Queue requests from the IP address

Your handler does not need to be written in the same language that created and enqueued the task if you write it in a separate service.

When you write you handler, follow these guidelines:

  • The code should return an HTTP status code within the range 200–299 to indicate success. Any other code indicates that the task failed.

  • Push tasks have a fixed completion deadline that depends on the scaling type of the service that's running them. Automatic scaling services must finish before 10 minutes have elapsed. Manual and basic scaling services can run up to 24 hours. If your handler misses the deadline, the Task Queue service assumes the failed and will retry it.

    When a task's execution time nears the deadline, App Engine raises a DeadlineExceededException before the deadline is reached, so you can save your work or log whatever progress was made.

  • It is important to consider whether the handler is idempotent. App Engine's Task Queue API is designed to invoke a given task only once. However, it is possible in exceptional circumstances, such as in the unlikely case of major system failure, that a task might execute multiple times. Your code must ensure that there are no harmful side-effects of repeated execution.

The response is only seen by the Task Queue service to determine if the task succeeded. The service discards the response, so your app will never see it. You should not include any application data in the response. If a task fails, the Task Queue service will retry the task by sending another request.

User-supplied data can be delivered in the request as a query string or as a payload in the request body. Inserting user data is described in Creating Tasks. If the request includes data, the handler must know how it was inserted into the request. The exact code you use to fetch the data from the request depends on the particular web framework you're using.

To test a task handler, sign in as an administrator and visit the handler's URL in your browser.

Reading request headers

A push task HTTP request can include these special headers, which contain task-specific information your handler might want to use:

Header Description
X-AppEngine-QueueName The name of the queue (possibly "default" for the default push queue).
X-AppEngine-TaskName The name of the task, or a system-generated unique ID if no name was specified.
X-AppEngine-TaskRetryCount The number of times this task has been retried. For the first attempt, this value is 0. This number includes attempts where the task failed due to a lack of available instances and never reached the execution phase.
X-AppEngine-TaskExecutionCount The number of times this task has previously failed during the execution phase. This number does not include failures due to a lack of available instances.
X-AppEngine-TaskETA The target execution time of the task, specified in seconds since January 1st 1970.
X-AppEngine-FailFast Indicates that a task running on a manual or basic scaled service fails immediately instead of waiting in a pending queue.

These headers are set internally by App Engine: If an external user request attempts to set these headers, they are removed. Therefore, if your request handler finds any of these headers in a request, that task queue request is guaranteed to be valid.

Headers are not removed when your app is running in the development server, or when a request is sent by a logged in administrator of the application.

Securing task handler URLs

If a task performs sensitive operations (such as modifying data), you might want to secure its worker URL to prevent a malicious external user from calling it directly. You can prevent users from accessing task URLs by restricting access to App Engine administrators. Task requests themselves are issued by App Engine and can always target restricted URL.

You can read about restricting URLs at Security and Authentication. An example you would use in web.xml to restrict everything starting with /tasks/ to admin-only is:


For more on the format of web.xml, see the documentation for the the deployment descriptor.

To test a task web hook, sign in as an administrator and visit the URL of the handler in your browser.

What's next