Skip to main content
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.
Looking for Sign’s long-lived event subscriptions instead? See Webhooks. The two mechanisms are configured differently and are not interchangeable.
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:
  • 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:
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.