Webhook Events

Complete catalog of all webhook event types and their payloads

Event Catalog

Formfex supports the following webhook events. Subscribe to any combination when creating or updating a webhook endpoint.

Form Events

`FORM_CREATED`

Fired when a new form is created.

json

{
  "type": "FORM_CREATED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "formId": "cm1a2b3c4d5e6f7g8h9i0j",
    "title": "Customer Feedback Survey"
  }
}

`FORM_PUBLISHED`

Fired when a form is published and starts accepting responses.

json

{
  "type": "FORM_PUBLISHED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "formId": "cm1a2b3c4d5e6f7g8h9i0j",
    "title": "Customer Feedback Survey",
    "shareUrl": "https://app.formfex.com/f/abc123"
  }
}

`FORM_UNPUBLISHED`

Fired when a form is unpublished and stops accepting responses.

json

{
  "type": "FORM_UNPUBLISHED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "formId": "cm1a2b3c4d5e6f7g8h9i0j",
    "title": "Customer Feedback Survey"
  }
}

`FORM_DELETED`

Fired when a form is deleted.

json

{
  "type": "FORM_DELETED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "formId": "cm1a2b3c4d5e6f7g8h9i0j",
    "title": "Customer Feedback Survey"
  }
}

`FORM_EXPIRED`

Fired when a form reaches its expiration date.

json

{
  "type": "FORM_EXPIRED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "formId": "cm1a2b3c4d5e6f7g8h9i0j",
    "title": "Customer Feedback Survey"
  }
}

Response Events

`FORM_RESPONSE_CREATED`

Fired when a new form response is submitted. This is the most commonly used event.

json

{
  "type": "FORM_RESPONSE_CREATED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "formId": "cm1a2b3c4d5e6f7g8h9i0j",
    "formTitle": "Customer Feedback Survey",
    "responseId": "cm9z8y7x6w5v4u3t2s1r0q",
    "answers": {
      "field_abc123": {
        "question": "How satisfied are you?",
        "answer": "Very satisfied"
      },
      "field_def456": {
        "question": "Any additional comments?",
        "answer": "Great product, keep it up!"
      }
    }
  }
}

Schema Mapping Fields (Optional)

When the form has a targetSchema configured (created via AI generation with a target schema), the following additional fields are included:

Field	Type	Description
`mappedData`	object	Response data mapped to the target schema. Fields with missing or invalid values are `null`.
`mappingReport`	object	Validation report with coverage metrics.
`mappingReport.totalFields`	number	Total fields in target schema.
`mappingReport.coveredFields`	string[]	Successfully mapped field keys.
`mappingReport.missingFields`	string[]	Fields not answered or not mapped.
`mappingReport.invalidFields`	array	Fields with type or enum mismatches.
`mappingReport.coveragePercent`	number	Percentage of fields successfully mapped (0-100).
`mappingReport.isComplete`	boolean	`true` when all fields are valid and present.

json

{
  "type": "FORM_RESPONSE_CREATED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "formId": "cm1a2b3c4d5e6f7g8h9i0j",
    "formTitle": "Customer Feedback Survey",
    "responseId": "cm9z8y7x6w5v4u3t2s1r0q",
    "answers": {
      "field_abc123": {
        "question": "What is your full name?",
        "answer": "John Doe"
      },
      "field_def456": {
        "question": "How old are you?",
        "answer": "30"
      },
      "field_ghi789": {
        "question": "Which department are you in?",
        "answer": "Engineering"
      }
    },
    "mappedData": {
      "fullName": "John Doe",
      "age": 30,
      "department": "Engineering"
    },
    "mappingReport": {
      "totalFields": 3,
      "coveredFields": ["fullName", "age", "department"],
      "missingFields": [],
      "invalidFields": [],
      "coveragePercent": 100,
      "isComplete": true
    }
  }
}

`FORM_RESPONSES_LIMIT_REACHED`

Fired when a form reaches its configured response limit and stops accepting new submissions.

json

{
  "type": "FORM_RESPONSES_LIMIT_REACHED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "formId": "cm1a2b3c4d5e6f7g8h9i0j",
    "formTitle": "Customer Feedback Survey"
  }
}

Analytics Events

`ANALYTICS_REPORT_COMPLETED`

Fired when an AI-powered Smart Analytics report finishes processing.

json

{
  "type": "ANALYTICS_REPORT_COMPLETED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "formId": "cm1a2b3c4d5e6f7g8h9i0j",
    "reportId": "rpt_abc123def456",
    "reportTitle": "Customer Feedback Analysis"
  }
}

Smart Form Events

`SMART_FORM_SESSION_COMPLETED`

Fired when a respondent finishes a smart form (AI-driven conversational form) session.

json

{
  "type": "SMART_FORM_SESSION_COMPLETED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "formId": "cm1a2b3c4d5e6f7g8h9i0j",
    "formTitle": "Hotel Checkout Survey",
    "sessionId": "ses_abc123def456",
    "answers": {
      "field_abc123": {
        "question": "How was your stay?",
        "answer": "Excellent, very comfortable"
      }
    }
  }
}

Field	Type	Description
`formId`	`string`	ID of the smart form
`formTitle`	`string`	Title of the smart form
`sessionId`	`string`	Unique identifier of the completed session
`answers`	`object`	Map of field IDs to question/answer pairs collected during the session

Schema Mapping Fields (Optional)

When the smart form has a targetSchema configured, the following additional fields are included in the payload:

Field	Type	Description
`mappedData`	`object`	Respondent's answers mapped to the target schema. Fields with missing or invalid values are set to `null`.
`mappingReport`	`object`	Validation report with coverage metrics.
`mappingReport.totalFields`	`number`	Total fields in the target schema.
`mappingReport.coveredFields`	`string[]`	Successfully mapped field keys.
`mappingReport.missingFields`	`string[]`	Fields not answered or not extractable from the conversation.
`mappingReport.invalidFields`	`array`	Fields with type or enum mismatches. Each entry has `key`, `issue`, `expected`, `received`, `value`.
`mappingReport.coveragePercent`	`number`	Percentage of fields successfully mapped (0–100).
`mappingReport.isComplete`	`boolean`	`true` when all fields are valid and present.

json

{
  "type": "SMART_FORM_SESSION_COMPLETED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "formId": "cm1a2b3c4d5e6f7g8h9i0j",
    "formTitle": "Hotel Checkout Survey",
    "sessionId": "ses_abc123def456",
    "answers": {
      "field_abc123": {
        "question": "How was your stay?",
        "answer": "Excellent, very comfortable"
      }
    },
    "mappedData": {
      "fullName": "John Doe",
      "age": 30,
      "department": null
    },
    "mappingReport": {
      "totalFields": 3,
      "coveredFields": ["fullName", "age"],
      "missingFields": ["department"],
      "invalidFields": [],
      "coveragePercent": 66.7,
      "isComplete": false
    }
  }
}

Subscription Events

`SUBSCRIPTION_CHANGED`

Fired when the account's subscription plan changes (upgrade, downgrade, or cancellation).

json

{
  "type": "SUBSCRIPTION_CHANGED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "previousPlan": "STARTER",
    "newPlan": "PRO",
    "changeType": "upgrade"
  }
}

`SUBSCRIPTION_PAYMENT_FAILED`

Fired when a subscription payment fails.

json

{
  "type": "SUBSCRIPTION_PAYMENT_FAILED",
  "created_at": "2026-03-06T12:00:00.000Z",
  "data": {
    "plan": "PRO",
    "failureReason": "card_declined"
  }
}

Quick Reference

Event	Description
`FORM_CREATED`	New form created
`FORM_PUBLISHED`	Form published (live)
`FORM_UNPUBLISHED`	Form unpublished
`FORM_DELETED`	Form deleted
`FORM_EXPIRED`	Form expired
`FORM_RESPONSE_CREATED`	New response submitted
`FORM_RESPONSES_LIMIT_REACHED`	Response limit hit
`ANALYTICS_REPORT_COMPLETED`	AI analytics report ready
`SMART_FORM_SESSION_COMPLETED`	Smart form session completed
`SUBSCRIPTION_CHANGED`	Plan changed
`SUBSCRIPTION_PAYMENT_FAILED`	Payment failed

PreviousDelete Webhook NextSecurity