GrabzIt Screenshot API Callback URL Setup

To set up a GrabzIt screenshot callback, create an absolute, publicly reachable URL for a server-side handler and pass it as the REST API callback parameter or to the callback argument in your client library. GrabzIt calls that URL when the capture is complete. Read the callback’s id and use it to retrieve the result. A localhost or 127.0.0.1 callback cannot be reached by GrabzIt. For local development, use the library’s synchronous SaveTo/save_to method where available. [REST API, callback URL troubleshooting, Node.js documentation]

How the callback flow works

Your server asks GrabzIt to create a screenshot and supplies a callback URL.
GrabzIt processes the capture asynchronously.
After completion, GrabzIt calls your handler with callback data, including the capture id.
Your handler uses that ID with the result retrieval method in your chosen client library, handles any reported errors, and stores or exposes the finished file.

The callback is a later notification, not an immediate response containing a screenshot ready to display. Design the application so the request and the completed image are separate states. [Node.js callback handler, displaying a screenshot after callback]

1. Create a reachable handler endpoint

Implement a stable server-side route such as https://app.example.com/hooks/grabzit. It must use an absolute URL and be accessible over the internet. Do not set the callback host to localhost or 127.0.0.1. If a new domain has not propagated yet, GrabzIt’s troubleshooting guidance suggests using the server IP temporarily. [Callback URL troubleshooting]

Keep the GrabzIt Application Key on your server. The REST API documentation cautions against calling the REST API from client-side code because that exposes the key. It also documents authorizing IP addresses to limit which servers can access the API; consult the REST reference for that configuration. [REST API]

2. Pass the callback URL in the capture request

REST API example

For the REST API, pass the handler as callback. URL-encode parameter values when constructing the request. This cURL example shows the request shape; substitute your Application Key and a publicly reachable handler URL.

curl -G 'https://api.grabz.it/services/convert' \
  --data-urlencode 'key=YOUR_APPLICATION_KEY' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'callback=https://app.example.com/hooks/grabzit' \
  --data-urlencode 'format=png'

Use the endpoint and required parameters from the current GrabzIt REST API reference for your account and capture type. The essential setup detail is that callback contains the handler URL. The API also documents customid, which is returned with a specified callback URL and can help correlate a capture with your own record.

Node.js client library

GrabzIt’s Node.js library documents the asynchronous save(callBackUrl, oncomplete) method. The exact setup also depends on the library’s initialization and result retrieval methods, so use its official documentation for your installed version.

// Capture setup and grabzit initialization follow the installed library's docs.
const callbackUrl = 'https://app.example.com/hooks/grabzit';

// The callback URL is the first argument; oncomplete is the library callback.
grabzit.save(callbackUrl, (id) => {
  console.log('GrabzIt capture ID:', id);
});

The Node.js documentation says the asynchronous save returns a unique identifier that can be used with get_result. It also documents save_to as the synchronous alternative without a callback URL. See the Node.js technical documentation.

3. Read callback data and retrieve the result

Official Node.js and Java callback handler documentation lists these callback values: id, filename, message, customId, format, and targeterror. The id identifies the capture; customId is the correlation value you supplied. Treat error-related fields such as message and targeterror as input to your error handling. Retrieve the result using the documented method for your language. [Node.js handler fields, Java handler fields]

A handler should validate that required fields are present, associate the callback with the corresponding capture record, retrieve the result by ID, and record completion or failure. Keep API credentials and result retrieval on the server. The callback field list is documented, but the sources do not prescribe a particular web framework or persistence layer.

Node.js handler outline

// Express-style outline. Wire get_result according to your GrabzIt library version.
app.get('/hooks/grabzit', async (req, res) => {
  const { id, filename, message, customId, format, targeterror } = req.query;

  if (!id) {
    return res.status(400).send('Missing capture id');
  }

  if (message || targeterror) {
    // Mark the associated capture as failed and retain the reported details.
    // Correlate with customId when your request supplied one.
    return res.status(200).send('Callback received');
  }

  try {
    // Retrieve the completed result by id using the library's documented API.
    // Store it or mark it ready for the application to retrieve.
    console.log({ id, filename, customId, format });
    return res.status(200).send('Callback received');
  } catch (error) {
    // Record retrieval failure and arrange a controlled retry/reconciliation path.
    return res.status(500).send('Result retrieval failed');
  }
});

This is a handler structure, not a drop-in GrabzIt SDK integration: method signatures for result retrieval vary by library. Follow the official documentation for your selected language rather than assuming parameter names or casing match between SDKs.

4. Support the asynchronous display flow

If a user starts a capture from a web page, the screenshot may not exist yet when that page’s request returns. Store a unique customId or another application-side correlation identifier, then provide a readiness check that reports whether the result is available. Display the screenshot after completion rather than expecting the initial request to contain it. GrabzIt’s support guide describes correlating with a unique customId and checking readiness server-side. [Display a screenshot with a callback handler]

5. Test the handler

Generate an existing capture first.
Open GrabzIt Diagnostics and select an item from the Out column.
Choose “Send to Callback Handler,” enter the handler URL, and provide optional fields such as a Custom ID.
Send the test and check that your server receives and processes the callback.

The documented Diagnostics flow tests the handler using an existing capture. [How to test a Callback Handler?]

Local development without a public callback

A callback cannot reach a private development server at localhost. When working locally, use the synchronous save option documented for your language library. The PHP API documents SaveTo; Node.js documents save_to. These save the result synchronously without requiring a public callback handler. Check the relevant library documentation for the method signature and destination path. [PHP API, Node.js technical documentation]

Callback versus synchronous save

Choice	Use it when	Requirement	Completion handling
Asynchronous callback	Your application can process a later completion notification.	A stable public handler URL.	Read callback fields, retrieve by ID, and update the capture state.
Synchronous `SaveTo`/`save_to`	You are developing locally or need the documented callback-free save flow.	A supported client library method.	The save operation completes through the synchronous library call.

The documentation establishes these behavioral differences but does not provide comparative performance measurements. Choose based on whether a public endpoint is available and whether your application can handle delayed completion.

Troubleshooting

Symptom	Likely cause	What to check
“You are trying to use a Callback URL that does not exist!”	The callback URL is invalid or not reachable from the public internet.	Use an absolute public URL, verify the route and DNS, and avoid localhost or 127.0.0.1. If a domain has not propagated, the support article suggests temporarily using the server IP. [Troubleshooting guide]
Handler receives no expected parameters	The request is reading the wrong parameter casing or callback format, or the handler route is not parsing query parameters.	Inspect the incoming request and follow the callback documentation for your language. The documented names include `id` and `customId`; casing varies across client libraries. [Node.js, Java]
Capture starts, but the page has no screenshot yet	The callback is asynchronous, so completion happens after the initiating request.	Track a correlation ID, expose readiness state, and display only after result retrieval succeeds. [Display guide]
Works on a deployed server but not on a developer machine	The callback host is local or otherwise unreachable to GrabzIt.	Use the synchronous `SaveTo`/`save_to` method during local development, or configure a publicly reachable handler. [PHP API, Node.js docs]
Handler receives an error indication	The callback includes `message` or `targeterror` information.	Record the fields, mark the capture state appropriately, and avoid treating an error callback as a successful result. [Callback fields]

Security, reliability, performance, and cost

Protect credentials: make capture requests from server-side code; the REST docs warn that client-side calls expose the Application Key. Consider the documented IP authorization controls. [REST API]
Handle delayed completion: store a capture state and correlation identifier so the application can show pending, ready, or failed status without assuming an immediate result.
Keep callback processing recoverable: record the received ID and relevant error fields before result retrieval, so you can diagnose handler or retrieval failures.
Expect network dependencies: DNS, public routing, and your handler availability affect callback delivery. The cited documentation does not state callback retry guarantees, so do not assume a particular retry policy.
Performance: callbacks avoid making the initiating page wait for the completed image, but they add an asynchronous handoff and result-retrieval step. The sources provide no benchmark figures; measure your own end-to-end flow.
Cost: the research sources provide no pricing figures. Check GrabzIt’s current pricing directly before estimating workload cost.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF, with no callback handler to deploy for a basic capture. Its API accepts screenshot parameters used by other screenshot APIs, which can make switching easier. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed, and response headers report the page verdict and billing status. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

FAQ

Can GrabzIt call a callback URL on my laptop?

No. A localhost or 127.0.0.1 address is not publicly reachable; use a supported synchronous save method for local work or a public handler URL.

Which callback value identifies the screenshot?

Use id to identify and retrieve the capture. Use customId when you need to correlate it with an application record.

Can I show the screenshot immediately after starting a callback capture?

Not reliably. Treat completion as asynchronous and show the image after your application confirms the result is ready.

How do I verify the handler without starting a new integration flow?

Use Diagnostics to select an existing capture and send it to the callback handler.