Outbound webhooks

Perform sends HTTP POST requests to external URLs in two situations. Both go through the same queue and the same delivery function.

Kind	Configured by	Target stored in	Signed
Registered hook	An API client, through `POST /v1/automation/hooks`	An `AutomationHook` row	Yes, with the hook’s secret
Flow webhook node	A coach, in the automation flow builder	The node itself, inside `TaskAutomation.flow`	No

Source: apps/core-api/src/modules/automation-hooks and apps/core-api/src/workers/hook-delivery-worker.ts.

Events

Event	`X-Perform-Event` header	Sent to	Fires when
Form filled	`FORM_FILLED`	Registered hooks subscribed to `FORM_FILLED`	A trainee submits any form, including signing a document to sign
Flow step	`automation_flow`	The URL on a flow’s webhook node	An automation flow run reaches that node

HOOK_EVENTS in automation-hooks.schema.ts has one entry today, FORM_FILLED. The event column is a string and the lane is generic. Adding an event is a new value in that list plus a call to a dispatcher from wherever the event happens.

The subscription name and the payload name differ in case. You subscribe to FORM_FILLED, the header says FORM_FILLED, and the payload’s event field is form_filled.

Registered hooks

Register

POST /v1/automation/hooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{ "event": "FORM_FILLED", "targetUrl": "https://example.com/hooks/perform", "formTemplateId": "FORM_ID" }

string

default:"FORM_FILLED"

One of HOOK_EVENTS.

string

required

Where deliveries go. Up to 2048 characters. Must be https on a public host.

string

Leave empty to receive every form. Set it to receive only that form. An id that is not in the studio is NOT_FOUND.

Response, in the automation envelope:

{
  "success": true,
  "message": "Success",
  "data": {
    "hook": {
      "id": "HOOK_ID",
      "event": "FORM_FILLED",
      "targetUrl": "https://example.com/hooks/perform",
      "formTemplateId": "FORM_ID",
      "active": true,
      "createdAt": "2026-10-07T08:00:00.000Z",
      "lastDeliveryAt": null,
      "lastStatus": null,
      "secret": "HOOK_SECRET"
    }
  }
}

The secret is 24 random bytes as hex. It is returned once, here, and never again, the way an API key is. Store it. Rules:

A key can hold at most 50 hooks (MAX_HOOKS_PER_KEY). The next one fails with BAD_REQUEST and a message telling you to delete one first.
Registering and removing a hook are audited as automation.hook.register and automation.hook.remove, because a webhook sends studio data to an address a partner chose.

The target URL fence

A hook URL is attacker-supplied as far as the server is concerned, and it is the server that makes the request. hookTargetUrl refuses anything that is not https, and any host matching localhost, 127., 10., 192.168., 169.254., 172.16. through 172.31., the IPv6 loopback, or a .local or .internal name.

List and remove

Route	Notes
`GET /v1/automation/hooks`	The hooks registered by the calling key. Optional query `event`. Never returns the secret. Each row shows `lastDeliveryAt` and `lastStatus`, which is the quickest way to see whether deliveries are landing.
`DELETE /v1/automation/hooks/:id`	Removes a hook the calling key owns. `NOT_FOUND` “webhook not found” otherwise.

Hooks are scoped to the key that registered them. One key cannot list or delete another key’s hooks, even in the same studio. Deleting a StudioApiKey row cascades to its hooks. A row in AutomationHook is a live subscription, not a setting a coach maintains. Make creates it when a scenario’s instant trigger is switched on and deletes it when it is switched off.

The `form_filled` payload

Built by buildFormFilledPayload in automation-hooks.dispatcher.ts.

{
  "event": "form_filled",
  "occurredAt": "2026-10-07T09:00:00.000Z",
  "studioId": "STUDIO_ID",
  "submissionNumber": 3,
  "formType": "INTAKE",
  "documentUrl": null,
  "form": { "id": "FORM_ID", "name": "Intake questionnaire", "type": "INTAKE" },
  "trainee": {
    "id": "CLIENT_ID",
    "name": "TRAINEE_NAME",
    "firstName": "FIRST_NAME",
    "lastName": "LAST_NAME",
    "phone": "0500000000",
    "email": "trainee@example.com",
    "externalId": null
  },
  "response": {
    "id": "RESPONSE_ID",
    "assignmentId": "ASSIGNMENT_ID",
    "formVersion": 2,
    "submittedAt": "2026-10-07T09:00:00.000Z",
    "answers": { "goal": "weight_loss", "injuries": null },
    "fields": [
      { "key": "goal", "label": "What is your goal?", "type": "goal", "value": "weight_loss" },
      { "key": "injuries", "label": "Injuries", "type": "text", "value": null }
    ]
  }
}

Field	Meaning
`event`	Always `form_filled`.
`occurredAt`	When the form was submitted. Falls back to the response’s creation time.
`studioId`	The studio.
`submissionNumber`	The ordinal of this submission among all forms this trainee has submitted in this studio, starting at 1. Counted across every form type. Computed at delivery time and not stored. Ties are broken by creation time and then by id, so the number is stable.
`formType`	Flat copy of `form.type`: `INTAKE`, `CHECK_IN`, `ONE_TIME` or `PDF_SIGNATURE`. Lets a scenario route without opening a nested object.
`documentUrl`	The signed PDF. Null unless the form was a document to sign.
`form`	`id`, `name`, `type`.
`trainee`	`id`, `name`, `firstName`, `lastName`, `phone`, `email`, `externalId`.
`trainee.externalId`	The id the API client supplied when it created the trainee, or null. The internal `externalUserId` column is never sent. Only an id in the `automation:<studioId>:` namespace is returned, with the namespace removed.
`response.assignmentId`	The form assignment this answers, or null.
`response.formVersion`	The form’s version when it was answered.
`response.answers`	The raw answers object keyed by field key.
`response.fields`	One entry per answerable field, in the order the trainee saw them (by page, then by order): `key`, `label`, `type`, `value`. Display-only blocks are left out. `value` is null for an unanswered field.

fields exists so a receiver can map an answer straight off the trigger with its label, without following ids back with a second call. It is built from the schema snapshot stored on the response, so it reflects the form as the trainee saw it. For a signed document, response.answers holds every value: the coach-filled fields, the trainee’s fields and the signature image URLs.

The flow webhook payload

Sent by webhookEffect in task-automations/flow-runtime.ts when a flow run reaches a webhook node.

{
  "event": "INACTIVE",
  "occurredAt": "2026-10-07T09:00:00.000Z",
  "trainee": { "name": "TRAINEE_NAME", "phone": "0500000000", "email": "trainee@example.com" },
  "program": "PLAN_NAME",
  "flowNode": "Notify CRM"
}

Field	Meaning
`event`	The automation’s trigger type, an `InboxItemType` value such as `INACTIVE`, `FORM_FILLED` or `NEW_CLIENT_IN_PLAN`.
`occurredAt`	When the node ran, not when the trigger fired.
`trainee`	`name`, `phone`, `email`. Each is null when the run has no trainee.
`program`	The trainee’s plan name (`Client.planName`), or null.
`flowNode`	The node’s label, or its id when the label is empty.

Headers: Content-Type: application/json and X-Perform-Event: automation_flow. There is no signature and no hook id, because there is no hook row and no stored secret. The URL was validated when the flow was saved, and the payload holds nothing the studio did not put in its own flow. A receiver that needs authentication should put an unguessable token in the URL. The FlowNodeExecution ledger makes sure a node is enqueued once per run, even across crash retries.

Delivery

Dispatch is best effort

dispatchFormFilled is called from forms.wiring.ts after the submission is saved, without awaiting it. No webhook is worth failing a trainee’s submission for. If queueing one delivery fails, it is logged and the others continue. Matching hooks are those in the studio, active, subscribed to the event, in a studio that is not archived, and either unscoped or scoped to that form.

Request

Header	Value
`Content-Type`	`application/json`
`X-Perform-Event`	The hook’s event, `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

Timeout: 10 seconds (TIMEOUT_MS). The response body is never read. It is cancelled so the socket is released.

Retries

Setting	Value
Queue	`automation-hook-deliver` (`PerformQueue.AUTOMATION_HOOK_DELIVER`)
Attempts	5
Backoff	Exponential from 10 seconds: roughly 10s, 40s, 2m40s, 10m40s
Concurrency	5

Receiver answers	Outcome
2xx	Delivered. `lastDeliveryAt` and `lastStatus` updated, `failureCount` reset to 0.
4xx other than 429	Permanent. Dropped at once and not retried. This is what Make returns once a scenario is deleted without detaching.
429, 5xx, timeout, network error	Retried. After the fifth attempt the worker logs “automation hook gave up”.
Hook deleted or inactive by delivery time	Dropped, “hook is gone”.

Every failed attempt increments failureCount and stamps lastStatus.

failureCount is recorded, and active exists on the row, but no code was found that switches a hook to inactive after repeated failures. A dead endpoint keeps receiving attempts for each new event until its hook is deleted.

Delivery is queued, so a receiver sees the event a moment after the submission, not during it. Deliveries for different events are not ordered. Use submissionNumber and occurredAt if order matters.

Verifying a delivery

Compute the HMAC over the raw body bytes, before parsing JSON. Parsing and re-serializing changes the bytes and the signature no longer matches.

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

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

Receivers should also:

Answer 2xx quickly and do the work afterwards. Anything slower than 10 seconds is a timeout and a retry.
Treat deliveries as at-least-once. A timeout after the receiver already processed the event leads to a second delivery. Deduplicate on response.id.
Answer 4xx only when the hook should stop receiving that delivery for good.

There is no timestamp in the signature, so a captured request can be replayed. Deduplicating on response.id covers that.

Testing

Register a hook with an empty formTemplateId.
Confirm it with GET /v1/automation/hooks.
Send yourself a form from the coach web app and fill it in the trainee app.
Check lastDeliveryAt and lastStatus on the hook.

The Make app wraps exactly these calls. See Make app.

​Events

​Registered hooks

​Register

​The target URL fence

​List and remove

​The form_filled payload

​The flow webhook payload

​Delivery

​Dispatch is best effort

​Request

​Retries

​Verifying a delivery

​Testing

Events

Registered hooks

Register

The target URL fence

List and remove

The `form_filled` payload

The flow webhook payload

Delivery

Dispatch is best effort

Request

Retries

Verifying a delivery

Testing