Boarding Form Webhook Payloads

Boarding form webhooks track a merchant's progress through onboarding in near real time — when a form is created, when the merchant first saves progress, every time they save, when they submit, and when an unfinished form lapses.

Together they replace polling the Forms API to discover state changes, and they make drop-off visible: you can see which merchants opened a form and stopped.

For creating and configuring the forms themselves, see Boarding Forms.

Lifecycle

flowchart TD
    A["Form created"] -->|form.created| B["Status: ACTIVE"]
    B --> C{"Merchant saves<br/>first section?"}
    C -->|"Yes — first save only"| D["form.started<br/>+ form.updated"]
    C -->|"Never — deadline passes"| E["form.expired<br/>Status: EXPIRED"]
    D --> F{"More saves?"}
    F -->|"Each save"| G["form.updated"]
    G --> F
    F -->|"Submitted"| H["form.completed<br/>+ form.updated<br/>Status: COMPLETED"]
    F -->|"Abandoned past deadline"| E

Payload

All five events share one envelope. data carries identifiers, status, and timestamps — plus the contact block for the person filling out the form, when one has been captured.

{
  "id": "what_test_6knw5fhtys9egrxtd6bt0txjhj",
  "webhookId": "wh_test_57vn6accfv9hrb5kqehv3k47tx",
  "eventType": "form.completed",
  "data": {
    "formId": "form_test_3r6j69gwvm81gapafn6c0dtmg2",
    "merchantId": "mid_test_wsqgngrn99gptndb1h2s70dzj",
    "status": "COMPLETED",
    "lastSectionCompleted": "banking",
    "completionDate": "2026-07-18T09:41:55Z",
    "modifiedOn": "2026-07-18T09:41:55Z",
    "personCompleting": {
      "firstName": "Jane",
      "lastName": "Roe",
      "email": "[email protected]",
      "phone": "+15125550143",
      "title": "CFO",
      "agreedOn": "2026-07-18T09:41:52Z",
      "ipAddress": "203.0.113.42"
    }
  }
}

Fields by event

Fields with no value are omitted rather than sent as null, so the exact key set depends on the event.

✅ always present ◻️ present only once captured

personCompleting

Present once the person completing the form has identified themselves. Every field within it is optional, and the block is omitted entirely if no values have been captured yet — so a form.created notification usually has no personCompleting, while a form.completed normally does.

agreedOn and ipAddress are stamped server-side, which is what makes them usable as evidence of acceptance. See Welcome Section for how the agreement is presented.

Event semantics

form.started means first saved progress

form.started fires when the merchant completes a section of the form for the first time — not when they open the link or view the first page. A merchant who opens a form and closes it without saving anything will never produce form.started.

This makes it a meaningful engagement signal rather than a page-view counter: a form with form.created but no form.started was never genuinely begun, which is a different re-engagement problem from one abandoned halfway through.

form.expired is an hourly sweep

Expiration is detected by a job that runs hourly, so form.expired arrives within about an hour of the deadline in expiresOn rather than exactly at it. Every other form event is emitted as it happens.

The sweep only considers forms whose status is ACTIVE. Two consequences: a form completed before its deadline is not eligible and will never emit form.expired even after expiresOn passes, and a form carrying no status value at all is never swept.

Delivery guarantees

form.created, form.started, form.completed, and form.expired are each designed to fire exactly once per form. form.updated fires once per save and is intentionally not once-only.

As with every Preczn webhook, this is not a substitute for idempotency in your handler — a retry can redeliver any notification. Deduplicate on the top-level id, key your updates off formId, and compare modifiedOn against your stored state. See Receiving and Verifying Webhooks.

FAQ