> ## Documentation Index
> Fetch the complete documentation index at: https://developers.gonitro.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Callbacks

> Attach a callback URL to an asynchronous Nitro PDF Services job and receive a single HTTP POST when the job has been created.

When you submit an asynchronous PDF Services job, you can ask Nitro to notify your
service rather than polling for it. Callbacks are **per-request**: each request opts
in or out on its own, configured in the request body, and fired once.

<Note>
  Looking for Sign's long-lived event subscriptions instead? See
  [Webhooks](/docs/build-nitro/sign-webhooks). The two mechanisms are configured
  differently and are not interchangeable.
</Note>

When you submit an asynchronous job (by setting the `Prefer: respond-async` header), you can include a `callback` URL inside the request's `delivery` block. Nitro will send a single `POST` to that URL once the job has been created, letting your service know that processing has started and where to fetch the result later.

There is no global registration, no event subscription, and no event stream. Each request opts in or out of a callback on its own.

## Providing a callback URL

Include a `callback` object inside the `delivery` field of the request body:

```json theme={null}
{
  "callback": {
    "URL": "https://your-domain.example/nitro/callbacks",
    "headers": [
      { "name": "Authorization", "value": "Bearer your-secret" }
    ]
  }
}
```

* `URL`: The `POST` endpoint Nitro should call. Required.
* `headers`: Optional list of `{ "name", "value" }` pairs sent on the callback request, useful for authenticating Nitro to your service.

The endpoint must accept `POST` requests.

## Callback payload

Nitro sends a JSON body containing the job ID and the URL to fetch the job's result:

```json theme={null}
{
  "jobID": "babe2aa7-9b5d-4eb2-a679-5fc12cf0a490",
  "location": "https://api.gonitro.dev/platform/jobs/babe2aa7-9b5d-4eb2-a679-5fc12cf0a490"
}
```

`GET <location>` returns the final response once processing completes. To poll progress before that, use `GET <location>/status`.

## When the callback fires

The callback is invoked **once**, immediately after the job record has been created. It is an acknowledgement that the request was accepted and is being processed, not a completion notification.

To know when the result is ready, poll the `location` URL, or use the `uploadResultTo` / `uploadResultsTo` delivery options to have Nitro upload the output file directly to your own endpoint or to a pre-signed S3 URL.

## See also

For per-endpoint context and the full `delivery` schema, see the request body of any Transformations, Extractions, or Conversions endpoint in the [PDF Services API reference](/docs/api-reference/platform/transformations/optimize).