Webhooks

NeuroPage POSTs to your URL when a page is ready, a job fails, a campaign sends a lead, or a lead acts on their page.

NeuroPage can POST to your URL when a landing page is hosted (page.ready), when an API or MCP job fails with no ready pages (job.failed), when a campaign sends a ready lead (lead.ready), and when the lead views the page, clicks, fills in the form or books a meeting.

There is no REST /webhooks endpoint. Subscriptions are created in two ways:

  1. MCP. subscribe_events registers an https callback (defaults to page.ready and job.failed) and returns a signing_secret once. list_event_subscriptions and unsubscribe_events manage those subscriptions. Writes need a live plan, like other MCP writes.
  2. The app. Open Integrations, Webhooks (https://neuropage.io/home/{workspace}/integrations) to add a webhook for lead.ready or landing-page activity. Those webhooks are not listed or removed through MCP.

You can still poll: GET /jobs/{id}?wait=50 (MCP: get_job) returns as soon as anything changes, and is how to read the pages themselves.

page.ready and job.failed fire for every campaign in the workspace, including the API campaign, with no Send-stage setup. Activity events (page.viewed, cta.clicked, form.submitted, meeting.booked) do the same. lead.ready still needs a campaign whose Autopilot, Send stage uses the webhook.

Set one up

  1. Open Integrations, Webhooks in the app (https://neuropage.io/home/{workspace}/integrations) and add a webhook: a name, an https URL, the events it takes, and optionally an auth header (name and value). The URL and header value are stored encrypted.
  2. Click Send test to post a sample of each event, and Activity to see every delivery: the body sent, your status code and the first 500 characters of your answer.
  3. For lead.ready: open the campaign, then Autopilot, Send. Pick Webhook as the tool, pick the webhook, and arm the stage. The campaign must be active with automatic page generation on before the API can add leads to it (409 campaign_not_eligible otherwise).

Events

  • lead.ready. A lead's page is ready and its campaign sends the lead to this webhook: the campaign's Autopilot, Send stage uses the tool Webhook with this webhook picked, and the stage is armed. NeuroPage first waits for everything the stage requires (the page, and email or LinkedIn messages when picked). A manual send from the campaign sends it too. Once per lead: a lead already sent is skipped unless you send it again from the campaign. A paused campaign sends nothing.
  • page.ready. A lead's landing page is hosted and has a permanent URL. Every campaign in the workspace, including pages made through the API or MCP. No Send-stage setup is required. Sent once per lead; a later successful delivery is not repeated.
  • job.failed. An API or MCP asset job ended with no ready pages (every accepted lead failed or was canceled). Not sent when the job is completed_with_errors. Sent once per job. The body is job-level: job_id, error, failed_lead_ids. Brand-from-website jobs are not included yet.
  • page.viewed. The lead starts a new visit to their page. Your own previews from the app do not count. Every campaign in the workspace, the API campaign included.
  • cta.clicked. The lead clicks the page's call to action. Every campaign in the workspace.
  • form.submitted. The lead submits the form on their page. Carries visitor_name and visitor_email when given. Every campaign in the workspace.
  • meeting.booked. The lead books a meeting through the Calendly or Cal.com embed on their page. Carries provider and scheduled_at. Every campaign in the workspace.

The payloads are under Webhook events in the API reference (webhooks in openapi.json).

Payload

One flat JSON object, so Clay, Zapier and Make map each key to a column. Every event has event, sent_at, lead_id, campaign_id, campaign_name, the contact (first_name, last_name, email, linkedin_url, company, job_title, company_domain), page_url and source_fields. lead.ready adds the messages the campaign wrote: email_subject_step_N, email_opening_step_N, email_body_step_N, li_connection_note, li_message_N. Empty steps are left out.

lead_id and campaign_id are uuids. The API ids are the same uuids with a prefix and no dashes: ast_ + lead_id is the asset, cmp_ + campaign_id is the campaign. To match a webhook to the row you sent, use that asset id or linkedin_url; external_ref is not in the webhook (it stays on the job's assets).

Delivery, auth and retries

  • Request. NeuroPage sends POST with Content-Type: application/json, User-Agent: NeuroPage-Webhooks/1.0 and, when set, your auth header. When the webhook has a signing secret (MCP subscriptions always do), it also sends X-NeuroPage-Signature: t=<unix>,v1=<hex>, where v1 is hex HMAC-SHA256 of ${t}.${body} with the signing secret. App-created webhooks stay unsigned unless a signing secret was stored. Answer with any 2xx within 15 seconds; redirects are not followed.
  • Auth. Requests are not signed (no HMAC). To make sure a request is from NeuroPage, set an auth header on the webhook (for example Authorization: Bearer <a long random secret>) and check it in your receiver. Use https only; private, loopback and link-local addresses are refused, when the webhook is saved and again before every delivery.
  • Retries. For lead.ready, a timeout, network error, 408, 429 or 5xx puts the send back on NeuroPage's job queue. The queue retries about every 30 seconds, but a lead's send is locked for 2 minutes after each attempt, so expect one or two more real attempts within a few minutes, not a long schedule. Any other answer (4xx, a redirect) is final. Activity events are sent once and not retried.
  • After a failure. The campaign shows the lead's send as failed; send it again from the campaign. Webhooks are best effort: if you need every page, also poll the job or list the campaign's assets (GET /assets?campaign_id=cmp_...).
  • Order and duplicates. Events are not ordered, and a retry can repeat one. Key your receiver on lead_id plus event.

Example: what your receiver gets

This is the request NeuroPage sends for lead.ready (the Send test sample), as curl, so you can point it at your own endpoint to test it:

bash
curl -X POST https://your-receiver.example.com/neuropage \
  -H "Content-Type: application/json" \
  -H "User-Agent: NeuroPage-Webhooks/1.0" \
  -H "Authorization: Bearer <the auth header value you set>" \
  -d '{"event":"lead.ready","sent_at":"2026-01-01T00:00:00.000Z","lead_id":"00000000-0000-0000-0000-000000000000","campaign_id":"00000000-0000-0000-0000-000000000000","campaign_name":"Test campaign","first_name":"Ada","last_name":"Lovelace","email":"ada@example.com","linkedin_url":"https://www.linkedin.com/in/ada-lovelace","company":"Analytical Engines","job_title":"Head of Growth","company_domain":"example.com","page_url":"https://pages.neuropage.io/example/ada-lovelace","email_subject_step_1":"A page we made for Analytical Engines","email_opening_step_1":"Ada, I put together a short page on how you could ...","li_connection_note":"Hi Ada, made something for you ...","li_message_1":"Here is the page I mentioned ...","source_fields":{"row_id":"r_123"}}'

And the job that makes such a page, sent into a campaign whose Send stage is your webhook:

bash
curl -X POST https://neuropage.io/api/v1/jobs \
  -H "Authorization: Bearer np_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "landing_page",
    "campaign_id": "cmp_...",
    "leads": [{ "linkedin_url": "https://www.linkedin.com/in/jane-doe", "external_ref": "row-1" }]
  }'

Recipe: Clay

Send rows from Clay to NeuroPage and get each page URL back in a Clay table, without polling.

  1. Receive. In Clay, make a table with a webhook as its source and copy the webhook URL Clay gives you.
  2. Register it. In NeuroPage, add that URL under Integrations, Webhooks with the event Lead ready. If your Clay webhook expects an auth header, put its name and value on the NeuroPage webhook. Click Send test: a sample row with page_url, first_name, company, email_subject_step_1 and the other keys appears in Clay, one column per key.
  3. Campaign. Make a campaign for these leads, set its Autopilot, Send stage to Webhook with that webhook, and arm it. Its API id is cmp_ plus the uuid at the end of the campaign's URL in the app, without dashes.
  4. Send. In the Clay table that holds your leads, add an HTTP API column: POST https://neuropage.io/api/v1/jobs, header Authorization: Bearer np_live_YOUR_KEY, body {"type":"landing_page","campaign_id":"cmp_...","leads":[{"linkedin_url":"<LinkedIn column>","first_name":"<First name>","company":"<Company>"}]}. One row is one lead, so one job per row.
  5. Match. Each lead.ready row in the receiving table carries linkedin_url and page_url; look rows up by linkedin_url to bring page_url and the message columns back next to your leads.

Mind the limits: 25 leads per job and 2 running page jobs per workspace, so for a large table, space the requests out; a 429 has a Retry-After header.