Getting Started

Webhooks

Receive real-time push notifications when your search tasks complete — faster and more reliable than polling. Set your webhook URL via the dashboard or PUT /v1/webhooks. Every delivery is signed with HMAC-SHA256 and retried on transient failure.

Events

Payload

{
  "timestamp": "2026-05-26T18:42:11.000Z",
  "event": "task.completed",
  "submission_id": "job_8291x_q",
  "total_leads": 10,
  "credits_used": 10,
  "credits_remaining": 188,
  "task": { "keyword": "Plumber", "city": "Austin", "max_leads": 10 }
}

Signature verification

Every request carries an X-Geolayer-Signature: sha256=<hex> header. Compute the same HMAC-SHA256 of the raw request body using your shared secret (set as OUTBOUND_WEBHOOK_SECRET; falls back to your JWT secret if unset). Compare with timing-safe equality — never ===.

app.post("/webhook", express.raw({type: "*/*"}), (req, res) => {
  const sig = req.headers["x-geolayer-signature"];
  const hmac = crypto.createHmac("sha256", process.env.SECRET);
  const expected = "sha256=" + hmac.update(req.body).digest("hex");
  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).end();
  }
  const event = JSON.parse(req.body.toString());
  // handle event.submission_id ...
  res.status(200).end();
});

import hmac, hashlib, os
from flask import request

@app.post("/webhook")
def webhook():
    sig = request.headers.get("X-Geolayer-Signature", "")
    expected = "sha256=" + hmac.new(
        os.environ["SECRET"].encode(),
        request.get_data(),
        hashlib.sha256,
    ).hexdigest()
    if not hmac.compare_digest(sig, expected):
        return "", 401
    event = request.get_json()
    # handle event["submission_id"] ...
    return "", 200

require "openssl"
require "json"

post "/webhook" do
  raw = request.body.read
  expected = "sha256=" + OpenSSL::HMAC.hexdigest(
    "SHA256", ENV["SECRET"], raw
  )
  sig = request.env["HTTP_X_GEOLAYER_SIGNATURE"].to_s
  halt 401 unless Rack::Utils.secure_compare(sig, expected)
  event = JSON.parse(raw)
  # handle event["submission_id"] ...
  200
end

$raw = file_get_contents("php://input");
$sig = $_SERVER["HTTP_X_GEOLAYER_SIGNATURE"] ?? "";
$expected = "sha256=" . hash_hmac(
    "sha256", $raw, getenv("SECRET")
);
if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
// handle $event["submission_id"] ...
http_response_code(200);

Retry behavior

• Failed deliveries retry 3 times with exponential backoff: immediate, +2s, +8s.
• A "failure" = non-2xx response, connection error, or timeout (10s).
• Final state (delivered or 3-times-failed) is logged in your dashboard under Developers → Webhook deliveries with the response body for debugging.
• Your endpoint should respond 200 within 5 seconds. If you need longer processing, queue the work and respond immediately.
• Idempotency: re-deliveries carry the same submission_id. Use it as your dedup key.

Test webhook

Send a signed test payload to your configured URL without running a real task:

curl -X POST https://geolayer.io/v1/webhooks/test \
  -H "Authorization: Bearer YOUR_API_KEY"

GET https://geolayer.io/v1/tasks/list-tasks

Returns your last 10 tasks (newest first). Tasks stuck in queued for more than 5 minutes are automatically retried up to 3 times before flipping to error.

Response (array)

• submission_id, status, created_at, last_retried, retry_count, error_log.
• payload: The original { keyword, city, max_leads } request body plus a diagnostics object once the task completes.

GET https://geolayer.io/v1/get-all-leads

Every lead ever returned to your account across every task, deduped by email and filtered through your suppression list. Useful for a one-shot CRM sync.

Response (array)

Same row shape as Fetch Task Results.

GET https://geolayer.io/v1/leads/export?keyword=Plumbers&city=Austin&limit=1000

Streams a CSV of up to limit rows (max 10,000) for a specific keyword + city. Pulls from the cache only — does not trigger live source fetches. Debits credits atomically; if your balance can't cover limit the request returns 402 without touching the data.

Query Parameters

/v1/suppression

Per-account do-not-contact list. Every read path (task results, get-all-leads, bulk export, lead lists) silently filters out matching emails. Use this for opt-outs, bounces, and CAN-SPAM/GDPR removal requests.

• GET /v1/suppression — list (most recent 1,000).
• POST /v1/suppression — body { "email": "..." , "reason": "user_added" } or { "emails": ["a@b.com", ...] } for bulk.
• DELETE /v1/suppression?email=foo@bar.com — remove one entry.

/v1/searches

Store and re-run searches without retyping the parameters.

• GET /v1/searches — list your saved searches.
• POST /v1/searches — body { "name": "Bay Area Plumbers", "keyword": "Plumber", "city": "San Jose" }.
• POST /v1/searches/run?id=N — submit a fresh task using a saved entry. Forwards to /v1/tasks/submit and returns the same { submission_id, status } response.
• DELETE /v1/searches?id=N — remove.

/v1/lists

Lightweight CRM-style grouping. Create lists, add lead IDs to them, read back members for export or sync. Suppression-list filtering is applied to membership reads.

• GET /v1/lists — all your lists with member_count.
• POST /v1/lists — create. Body { "name": "Top Pipeline Q3" }.
• GET /v1/lists?id=N — members (full lead rows, same shape as task results).
• POST /v1/lists?id=N — add members. Body { "lead_ids": [123, 124] }.
• DELETE /v1/lists?id=N — delete the list (cascades members).

/v1/webhooks

Manage your outbound webhook URL programmatically. See the Webhooks section above for the payload format and signature scheme.

• GET /v1/webhooks — { webhook_url, signing_secret_env, signature_header, events: [...] }.
• PUT /v1/webhooks — body { "url": "https://your.server/hook" }. Validated as an http(s) URL.
• DELETE /v1/webhooks — clear the URL (stops outbound deliveries).
• POST /v1/webhooks/test — send a signed test.webhook payload to the configured URL. Response includes delivered, attempts, last_status.