# 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](https://docs.neuropage.io/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.
