Webhooks API

Apex has three webhook surfaces. They are not interchangeable.

Surface	Path	What it is
Inbound source	`/api/webhooks`	Register a named source so an outside system can POST signed events into Apex
Operator alerts	`/api/notifications`	Apex calls your URL (or Slack) when an experiment starts or finishes
Journey destination	`/api/webhook-destinations`	An HTTPS endpoint a journey Webhook step can call

All management endpoints need a session or an apex_sk_ key. Incoming POSTs to a source use that source's signing secret, not your API key.

Inbound sources

https://app.apex.inc/api/webhooks/<source>

Apex maps fields from the payload into analytics rows. This path does not write revenue events today.

GET/api/webhooks

List inbound sources for the workspace.

curl https://app.apex.inc/api/webhooks \ -H "x-api-key: apex_sk_..."

POST/api/webhooks

Parameter	Type	Description
`source`required	`string`	Lowercase identifier. Letters, numbers, dashes, underscores. Becomes the URL path.
`fieldMapping`	`object`	Map payload fields to Apex metric fields. Dot-paths allowed (e.g. data.email → email).

curl -X POST https://app.apex.inc/api/webhooks \ -H "Content-Type: application/json" \ -H "x-api-key: apex_sk_..." \ -d '{ "source": "billing", "fieldMapping": { "customer.email": "email", "amount": "value" } }'

The response includes secret (prefix whsec_). Store it. Apex only returns it at create time. The other system must sign the raw body with HMAC-SHA256 and send one of:

x-webhook-signature
x-hub-signature-256
stripe-signature

Unsigned or badly signed POSTs are rejected.

DELETE/api/webhooks

Remove an inbound source.

Parameter	Type	Description
`source`required	`string`	Source identifier (query string, not a body id).

curl -X DELETE "https://app.apex.inc/api/webhooks?source=billing" \ -H "x-api-key: apex_sk_..."

POST/api/webhooks/:source

Receive a signed payload from the other system.

The other system POSTs JSON to this URL. Apex verifies the signature against the stored secret, maps fields, and records the event.

There is no HubSpot- or Stripe-shaped shortcut at /api/webhooks/hubspot. Those products have their own integration methods. Use this route for a custom source you registered.

Operator alerts (Apex → you)

To hear when an experiment starts or finishes, create a notification config. This is not /api/webhooks.

POST/api/notifications

Create a webhook or Slack alert. Workspace admin only.

Parameter	Type	Description
`type`required	`string`	`webhook` or `slack`.
`url`	`string`	Required when type is webhook. HTTPS URL Apex will POST to.
`webhookUrl`	`string`	Required when type is slack. Incoming Slack webhook URL.
`channel`	`string`	Slack channel label. Defaults to #general.
`triggers`	`array`	Events to subscribe to. Unknown values are dropped.
`headers`	`object`	Extra headers on webhook deliveries.

Triggers the create endpoint accepts:

Trigger	Fired when
`experiment.started`	An experiment starts running
`experiment.completed`	An experiment finishes
`task.created`	A workspace task is created
`budget.recommendation`	A budget recommendation is ready
`model.drift`	Scoring drift is detected
`scoring.changed`	Scoring weights change

There is no goal.reached, lead.created, or connector.synced trigger.

curl -X POST https://app.apex.inc/api/notifications \ -H "Content-Type: application/json" \ -H "x-api-key: apex_sk_..." \ -d '{ "type": "webhook", "url": "https://example.com/hooks/apex", "triggers": ["experiment.started", "experiment.completed"] }'

GET/api/notifications

List alert configs. Add ?logs=true to include recent delivery attempts.

DELETE/api/notifications

Remove an alert. Pass ?id=notif_… . Workspace admin only.

Journey destinations (Apex → your stack)

A journey Webhook step does not take a raw URL. Register the destination first at Set up Apex (webhook destinations), then pick it on the step.

GET/api/webhook-destinations

List destinations. Signing keys are redacted.

POST/api/webhook-destinations

Parameter	Type	Description
`name`required	`string`	Label on the journey canvas.
`baseUrl`required	`string`	HTTPS URL. Private IPs and metadata hosts are rejected.
`description`	`string`	Shown in the picker.
`id`	`string`	Stable id. Letters, numbers, dash, underscore. Apex mints one if omitted.

Each destination gets its own HMAC signing key. Rotate it at POST /api/webhook-destinations/:id/rotate. Send a test ping at POST /api/webhook-destinations/:id/ping.

Events API — the snippet and SDK ingest path
Server Events — authenticated backend events
Journeys API — Webhook steps reference a destination id

Webhooks API

Inbound sources

Operator alerts (Apex → you)

Journey destinations (Apex → your stack)

Related