Automation hooks

An automation hook is a webhook subscription. An automation platform such as Make registers one when a scenario’s instant trigger is switched on and deletes it when the trigger is switched off. When a subscribed event happens in the studio, Perform posts a JSON payload to the hook’s URL. Source: backend/apps/core-api/src/modules/automation-hooks/. The module has a controller, service, repository, schema, dispatcher and delivery file, and no routes file of its own.

Mounting and auth

The controller is built and mounted inside automationApiRouter(ctx) in modules/automation-api/automation-api.routes.ts:

router.post('/hooks', hooks.register);
router.get('/hooks', hooks.list);
router.delete('/hooks/:id', hooks.remove);

modules/index.ts mounts that router at /v1/automation with no web lane middleware, so the full paths are /v1/automation/hooks. The general /v1 rate limiter from app.ts applies. Authentication is requirePartnerKey from modules/partner/partner-auth.ts, applied to the whole /v1/automation router:

The request must send Authorization: Bearer YOUR_API_KEY, where the key starts with pf_live_. Anything else fails with missing partner api key.
The key is hashed with SHA-256 and looked up through the partner repository. A key that is unknown, revoked, or whose studio is archived fails with invalid partner api key.
On success the request carries partner with studioId and apiKeyId. lastUsedAt on the key is stamped at most once every 5 minutes.

Keys are studio API keys, the same ones the /v1/partner lane uses. There are no roles on this lane. One key maps to exactly one studio.

Response envelope on this lane

/v1/automation does not use the standard envelope described in API overview. It uses automation-api.envelope.ts. Success is always HTTP 200:

{ "success": true, "message": "Webhook registered", "data": {} }

Errors carry a readable sentence and no error code field:

{ "success": false, "message": "Invalid request: targetUrl must be an https URL on a public host" }

Status mapping in automationErrorMiddleware:

Error	HTTP status
Zod validation error	400, message starts with `Invalid request:` and lists up to 5 issues
`AppError` `UNAUTHORIZED`	401
`AppError` `FORBIDDEN`	403
`AppError` `CONFLICT`	409
`AppError` `RATE_LIMITED`	429
`AppError` `SERVICE_UNAVAILABLE`	503
`AppError` `INTERNAL`	500
Any other `AppError`, including `NOT_FOUND`, `BAD_REQUEST` and `VALIDATION`	400
Anything else	500

So a hook that does not exist answers 400 here, not 404.

Events

HOOK_EVENTS in automation-hooks.schema.ts has one value: FORM_FILLED.

Endpoints

`POST /v1/automation/hooks`

Registers a webhook for the calling API key. Auth: studio API key (requirePartnerKey).

string

default:"FORM_FILLED"

Only FORM_FILLED is accepted.

string

required

Trimmed, a valid URL, up to 2048 characters. Must use https and a public host. Hosts that are refused: localhost, addresses starting with 127., 10., 192.168., 169.254. or 172.16. to 172.31., the IPv6 loopback, and names ending in .local or .internal.

string

Limits the hook to one form. Empty, blank or null means every form of the studio.

What the service does:

Counts the hooks already registered by this key. At MAX_HOOKS_PER_KEY = 50 the request is refused.
When formTemplateId is sent, checks that the form template belongs to the key’s studio.
Generates a signing secret (24 random bytes, hex encoded) and creates the AutomationHook row.
Writes an AuditLog row with action automation.hook.register, actorId set to the API key id, resourceType AUTOMATION_HOOK and the hook id.

Response: message Webhook registered. data.hook contains the hook and its secret. The secret is returned only here. The list endpoint never returns it.

{
  "success": true,
  "message": "Webhook registered",
  "data": {
    "hook": {
      "id": "cmf1hook0001",
      "event": "FORM_FILLED",
      "targetUrl": "https://hook.example.com/perform/form-filled",
      "formTemplateId": null,
      "active": true,
      "createdAt": "2026-10-07T09:00:00.000Z",
      "lastDeliveryAt": null,
      "lastStatus": null,
      "secret": "YOUR_HOOK_SECRET"
    }
  }
}

Errors:

401 missing partner api key or invalid partner api key.
400 Invalid request: ... for a schema failure, for example targetUrl must be an https URL on a public host.
400 this key already has 50 webhooks; delete one before adding another (BAD_REQUEST).
400 form not found (NOT_FOUND) when formTemplateId is not in the studio.

`GET /v1/automation/hooks`

Lists the hooks registered by the calling API key, newest first. Hooks registered by another key of the same studio are not included. Auth: studio API key.

string

Optional filter. Only FORM_FILLED is accepted.

Response: message Webhooks listed.

{
  "success": true,
  "message": "Webhooks listed",
  "data": {
    "hooks": [
      {
        "id": "cmf1hook0001",
        "event": "FORM_FILLED",
        "targetUrl": "https://hook.example.com/perform/form-filled",
        "formTemplateId": "cmf1form0001",
        "active": true,
        "createdAt": "2026-10-07T09:00:00.000Z",
        "lastDeliveryAt": "2026-10-07T10:14:02.000Z",
        "lastStatus": 200
      }
    ]
  }
}

lastDeliveryAt and lastStatus are updated after each delivery attempt. lastStatus is null when the last attempt got no HTTP response. The stored failureCount is not returned. Errors: 401 for a bad key. 400 Invalid request: ... for an unknown event.

`DELETE /v1/automation/hooks/:id`

Removes one hook. The delete is scoped to the calling key, so a key cannot remove a hook another key registered. Auth: studio API key.

string

required

The hook id.

Deletes the row and writes an AuditLog row with action automation.hook.remove. Response: message Webhook removed.

{ "success": true, "message": "Webhook removed", "data": { "deleted": true } }

Errors: 400 webhook not found (NOT_FOUND) when no row matched the id for this key. 401 for a bad key.

The `AutomationHook` row

Field	Notes
`id`	cuid
`studioId`, `apiKeyId`	Owner studio and the key that registered it. Deleting the studio, the key or the form template cascades
`event`	String column. `FORM_FILLED` today
`targetUrl`	Where deliveries are posted
`formTemplateId`	`null` means every form
`secret`	HMAC signing secret. Never read back through the API
`active`	Default true. No endpoint in this module changes it
`lastDeliveryAt`, `lastStatus`	Result of the latest attempt
`failureCount`	Incremented on a failed attempt, reset to 0 on a successful one. Nothing in this module reads it

Dispatcher

automation-hooks.dispatcher.ts turns a studio event into queued deliveries.

Who emits

The only emitter of FORM_FILLED is formSubmittedHandler(ctx) in modules/forms/forms.wiring.ts. It is the submit hook of the wired forms service (createWiredFormsService), so it runs for every submission that goes through that service. See Forms. It calls dispatchFormFilled(ctx.prisma, hookQueue, event, ctx.logger) first and without awaiting it, so the trainee’s submit does not wait on Redis and a task automation failure cannot cost the webhook. A failure to dispatch is logged as automation hooks: dispatch failed. After that the same handler runs the FORM_FILLED and FORM_RATING_BELOW task automations described in Tasks engine. The forms service built inside automation-api.routes.ts is constructed without a submit hook.

`dispatchFormFilled`

repo.matching(studioId, 'FORM_FILLED', formTemplateId) loads active hooks of the studio for that event whose formTemplateId is null or equals the submitted form. Hooks of an archived studio are excluded.
With no matching hook it returns 0 and does no further work.
buildFormFilledPayload builds one payload. It returns null when the response row is gone, and nothing is queued.
One job per hook is added to the queue with the hook id and the shared payload. A queueing failure for one hook is logged and the others continue.

Payload: `form_filled`

{
  "event": "form_filled",
  "occurredAt": "2026-10-07T10:14:00.000Z",
  "studioId": "cmf1studio001",
  "submissionNumber": 4,
  "formType": "CHECK_IN",
  "documentUrl": null,
  "form": { "id": "cmf1form0001", "name": "Weekly check-in", "type": "CHECK_IN" },
  "trainee": {
    "id": "cmf1client001",
    "name": "Dana Levi",
    "firstName": "Dana",
    "lastName": "Levi",
    "phone": "0501234567",
    "email": "dana@example.com",
    "externalId": "crm-4821"
  },
  "response": {
    "id": "cmf1resp0001",
    "assignmentId": "cmf1assign001",
    "formVersion": 3,
    "submittedAt": "2026-10-07T10:14:00.000Z",
    "answers": { "weight": 71.4, "energy": 4 },
    "fields": [
      { "key": "weight", "label": "Weight", "type": "number", "value": 71.4 },
      { "key": "energy", "label": "Energy this week", "type": "rating", "value": 4 }
    ]
  }
}

Field	Source
`event`	Always `form_filled` (lowercase), unlike the `FORM_FILLED` value used to subscribe
`occurredAt`	`FormResponse.submittedAt`, falling back to `createdAt`
`submissionNumber`	1 plus the count of this trainee’s earlier submitted responses across all of the studio’s forms, ordered by `submittedAt`, then `createdAt`, then id. It is computed at dispatch time and not stored
`formType`	Flat copy of `form.type`
`documentUrl`	The signed PDF. `null` unless the form was a document to sign
`form`	`id`, `name`, `type` of the template
`trainee`	`id`, `name`, `firstName`, `lastName`, `phone`, `email`, and `externalId`
`trainee.externalId`	The id the partner supplied when creating the trainee. It is read from `Client.externalUserId` only when that value starts with `automation:<studioId>:`. Any other value there is an app account id and is reported as `null`
`response.answers`	The raw answers object keyed by field key
`response.fields`	One entry per answerable field from the response’s schema snapshot, sorted by page and order, with `key`, `label`, `type` and `value`. Display-only field types are left out. An unanswered field has `value` `null`

Delivery

deliverHook(prisma, job, logger) in automation-hooks.delivery.ts posts one payload. It has two modes, selected by the job.

Registered hooks

The job carries hookId. The worker loads the hook. A hook that is gone or not active is dropped without a request. The body is JSON.stringify(payload). The request is an HTTP POST to targetUrl with a 10 second timeout and these headers:

Header	Value
`Content-Type`	`application/json`
`X-Perform-Event`	The hook’s `event`, for example `FORM_FILLED`
`X-Perform-Hook-Id`	The hook id
`X-Perform-Signature`	`sha256=` followed by the hex HMAC-SHA256 of the exact request body, keyed with the hook’s secret

To verify a delivery, compute the same HMAC over the raw body bytes with the secret returned at registration and compare it to the header.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody: string, header: string, secret: string): boolean {
  const expected = `sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`;
  return (
    header.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected))
  );
}

The response body is never read. After the attempt, recordDelivery stamps lastDeliveryAt and lastStatus, and increments failureCount or resets it to 0.

Direct webhooks from flows

The job carries directUrl and no hook id. This is the Webhook node of the flow builder. See Task automations. There is no hook row and no secret. The request is a POST with Content-Type: application/json and X-Perform-Event set to the job’s event (automation_flow). There is no X-Perform-Signature and no X-Perform-Hook-Id header, and nothing is recorded on a hook row. The body is the flow payload:

{
  "event": "INACTIVE",
  "occurredAt": "2026-10-07T09:00:00.000Z",
  "trainee": { "name": "Dana Levi", "phone": "0501234567", "email": "dana@example.com" },
  "program": "3 months",
  "flowNode": "CRM update"
}

Here event is the task trigger type of the flow run.

Outcomes and retries

Result of the attempt	Outcome
2xx	Delivered
4xx other than 429	Permanent failure. Logged as `automation hook dropped` and not retried
429, 5xx, timeout or network error	Retried
Hook missing or inactive, or a job with no target	Dropped, not retried

Queueing and retries live in workers/hook-delivery-worker.ts:

Queue: automation-hook-deliver (PerformQueue.AUTOMATION_HOOK_DELIVER), job name deliver.
createHookQueue(ctx).enqueue adds the job with 5 attempts and exponential backoff starting at 10 seconds.
startHookDeliveryWorker(ctx) is started from server.ts with concurrency 5. It throws only when the outcome asks for a retry, which is what makes BullMQ schedule the next attempt.
After the last attempt the failure is logged as automation hook gave up. Completed jobs are removed. The last 100 failed jobs are kept.

A hook is not deactivated automatically after repeated failures. failureCount keeps counting until a delivery succeeds.

Who uses the hook queue

Producer	Mode	Event header
`formSubmittedHandler` in `forms/forms.wiring.ts`, through `dispatchFormFilled`	Registered hooks	`FORM_FILLED`
`webhookEffect` in `task-automations/flow-runtime.ts`	Direct URL	`automation_flow`

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Automation hooks

Mounting and auth

Response envelope on this lane

Events

Endpoints

`POST /v1/automation/hooks`

`GET /v1/automation/hooks`

`DELETE /v1/automation/hooks/:id`

The `AutomationHook` row

Dispatcher

Who emits

`dispatchFormFilled`

Payload: `form_filled`

Delivery

Registered hooks

Direct webhooks from flows

Outcomes and retries

Who uses the hook queue

​Mounting and auth

​Response envelope on this lane

​Events

​Endpoints

​POST /v1/automation/hooks

​GET /v1/automation/hooks

​DELETE /v1/automation/hooks/:id

​The AutomationHook row

​Dispatcher

​Who emits

​dispatchFormFilled

​Payload: form_filled

​Delivery

​Registered hooks

​Direct webhooks from flows

​Outcomes and retries

​Who uses the hook queue

Mounting and auth

Response envelope on this lane

Events

Endpoints

`POST /v1/automation/hooks`

`GET /v1/automation/hooks`

`DELETE /v1/automation/hooks/:id`

The `AutomationHook` row

Dispatcher

Who emits

`dispatchFormFilled`

Payload: `form_filled`

Delivery

Registered hooks

Direct webhooks from flows

Outcomes and retries

Who uses the hook queue