Get API Webhooks When Your List Is Ready
Add a callback_url to a Google Maps Scraper order and MapsDaddy posts a signed event when it starts, is delivered or is cancelled. Here's how to verify and handle it.
4 min read
API webhooks let MapsDaddy tell your system when a list is ready, so your script doesn't have to keep asking. You add a callback_url when you start a Google Maps scrape, and we send a signed message to it each time the order changes. This guide covers the events, the headers, how to check the signature, and how retries work.
How API Webhooks Work
When you call POST /google-maps-scraper, add a callback_url to the body. It must be a public HTTPS address on a server you control. Private network addresses and localhost aren't accepted. If you haven't started an order through the API yet, read Start a Google Maps Scrape With the API first.
Each time the order moves to a new stage, we send a POST with a JSON body to that address. Your server should reply with any 2xx status within 10 seconds. We don't follow redirects, so point the URL at the final address.
Webhooks are for Google Maps Scraper orders only. Local Business Database exports and enrichment runs don't send webhooks, so poll those instead: GET /business-database/exports/{export_id} for an export, and GET /lists/{list_id}/enrichments or GET /orders/{run_id} for an enrichment run.
The Three Events
| Event | What it means | What you'd usually do |
|---|---|---|
order.processing | The scrape started. | Update a status field, if you track one. |
order.delivered | The file is ready. download_url is included. | Download the list and start whatever comes next. |
order.cancelled | The order was cancelled and its credits refunded. | Mark it cancelled and let someone know. |
Write your handler so it ignores event names it doesn't know, rather than failing. Then it keeps working if we add more later.
What a Webhook Looks Like
Each request carries these headers:
X-MapsDaddy-Event: the event name, likeorder.delivered.X-MapsDaddy-Signature:sha256=followed by a signature of the body.Content-Type: application/json
The body looks like this (shortened):
{
"id": "whd_7c2e9a41f0b84d16a3c5",
"event": "order.delivered",
"created_at": "2026-11-10T09:24:52.000Z",
"data": {
"order_id": "ord_8f2c41d9a7b34e01",
"order_number": 1042,
"status": "completed",
"delivered_count": 684,
"status_url": "...",
"download_url": "..."
}
}
The data object also has service, credits and cancel_reason.
Check the Signature
Your callback address is on the public internet, so anyone who finds it could send it a fake message. The signature proves the message came from us.
When you create an order with a callback_url, the response includes a callback_signing_secret. It's shown only once, so store it with the order ID. To check a webhook, work out the HMAC SHA-256 of the raw request body using that secret, write it as hex, put sha256= in front, and compare it with the X-MapsDaddy-Signature header using a constant-time check. In Node.js:
import crypto from "node:crypto";
// rawBody: the request body exactly as received, before JSON parsing
function isValidSignature(rawBody, signatureHeader, secret) {
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signatureHeader ?? "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
The same check in Python:
import hmac, hashlib
def is_valid_signature(raw_body: bytes, header: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header or "")
Tip: Always check the raw body exactly as it arrived. If you parse the JSON and turn it back into text, spacing can change and the signature won't match.
Retries and Duplicates
If your server is down, slow or replies with an error, we try again. Each event gets up to 5 attempts in total, with waits of about 30 seconds, 2 minutes, 8 minutes and 32 minutes between them. That means you can receive the same event more than once, so plan for it:
- Reply fast. Check the signature, save the event, return
200. Do slow work like downloading or CRM imports afterwards in a background job. - Skip repeats. Every webhook has an
id. If you've already handled that id, just reply200again. - Keep a fallback. If your server was offline through every retry, nothing is lost.
GET /orders/{order_id}always shows the current status, and the list stays in Lists & Exports for 180 days.
A Simple Handler Flow
- Receive the
POSTat your callback address. - Check the signature against the raw body. If it fails, reply
401and stop. - Read the event name and
order_id. - If you've handled this webhook
idbefore, reply200and stop. - Save the event and reply
200. - In a background job, on
order.delivered, fetch the file fromdownload_url, or callGET /lists/{list_id}/downloadwith your key. - Pass it on: import to your CRM, save to shared storage, or tell the team.
For example, an agency might start a weekly scrape for roofers in Dallas, Texas. When order.delivered arrives, their handler downloads the list, removes businesses already in the CRM and posts a short summary in the team chat.
Test Before You Go Live
Start a small order, one category in one location, with the callback pointed at a test endpoint that logs every header and body. Check you get order.processing and then order.delivered, that the signature check passes, and that the download works. The API documentation has the full payload, and our post on automating Google Maps exports shows a complete setup.
Ready to try it?
Start your export with MapsDaddy. No browser extension, Google account or API key needed.
Related Guides
Still stuck?
Our team usually replies the same day.