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

EventWhat it meansWhat you'd usually do
order.processingThe scrape started.Update a status field, if you track one.
order.deliveredThe file is ready. download_url is included.Download the list and start whatever comes next.
order.cancelledThe 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, like order.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 reply 200 again.
  • 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

  1. Receive the POST at your callback address.
  2. Check the signature against the raw body. If it fails, reply 401 and stop.
  3. Read the event name and order_id.
  4. If you've handled this webhook id before, reply 200 and stop.
  5. Save the event and reply 200.
  6. In a background job, on order.delivered, fetch the file from download_url, or call GET /lists/{list_id}/download with your key.
  7. 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.

Start Your Export

Still stuck?

Our team usually replies the same day.

Contact support
Get API Webhooks When Your List Is Ready