Deploy hook

Your site's hook URL is shown in the dashboard:

https://headlark.com/api/v1/hook?token=<secret key>

After a production deploy, Headlark reads your /sitemap.xml (or just your home page if there is none), fetches each page from your live site, and writes its SEO. A sitemap index (WordPress, Astro's /sitemap-index.xml, Next.js) is followed one level. Pages that haven't changed come from cache at once; new or changed pages are written in a batch and published within minutes. A large site that doesn't fit in one run is continued by the next scheduled run.

Vercel, Netlify and Webflow get an answer at once (202) and the pages are processed in the background: those platforms don't wait for a long crawl, and would retry the call or switch the webhook off.

Vercel

Team Settings → Webhooks → add a webhook for deployment.succeeded pointing at the hook URL (Vercel offers account webhooks on Pro; on Hobby, call the hook from CI as below). Only production deploys are processed; preview deploys are ignored.

Netlify

Site configuration → Notifications → Deploy notifications → Outgoing webhook, event "Deploy succeeded", URL = the hook URL. Only the production context is processed.

Any CI or script

curl -X POST "https://headlark.com/api/v1/hook" \
  -H "authorization: Bearer $HEADLARK_KEY" \
  -H "content-type: application/json" \
  -d '{"url": "https://example.com"}'

Where you can set a header, send the key this way instead of in the URL: URLs end up in logs and webhook histories. Keep the key in your CI's secret store.

A call like this waits for the crawl; the response lists every page with cached (applied now), queued (being written), deferred (continued by the next scheduled run) or an error. With review mode on, pending marks a page whose new SEO waits for your approval; it's published when you approve it.

Pages that fail

returned 401, 403, 429 or 503: something in front of your site turned Headlark away: a password, Vercel Deployment Protection, or a bot firewall such as Cloudflare Bot Fight Mode. Allow the user agent Headlark/1, or use the build step, which needs no crawl.
Only your site's own domains (and their subdomains) are crawled, over HTTPS; sitemap entries on other hosts, and URLs with a query string (?page=2), are skipped. The snippet looks plans up by path, so those pages need the build step.

Where the SEO goes

A deploy hook can't change the HTML your host already serves. The results are published for the snippet (and written into Webflow for Webflow sites). For tags in the HTML itself, use the build step.