Webhook Events

Formtorch delivers three event types. You choose which ones an endpoint subscribes to when you create or update it.

Payload envelope

All events share the same JSON structure:


{
  event: string; // event name, e.g. "form.submitted"
  timestamp: string; // ISO 8601, when the delivery was created
  delivery_id: string; // unique ID for this delivery attempt
  form: {
    id: string;
    name: string;
  }
  submission: {
    id: string;
    created_at: string; // ISO 8601, when the submission was received
    data: Record<string, unknown>; // submitted field values
    is_test: boolean;
    is_spam: boolean;
  }
}

submission.data contains all submitted fields except reserved _* fields (_redirect, _honeypot, _formName, _test), which are stripped before delivery.

form.submitted

Fires when a real, non-spam, non-test submission is received. This is the primary event for processing leads and contact form entries.

Example payload


{
  "event": "form.submitted",
  "timestamp": "2025-03-15T14:30:00.000Z",
  "delivery_id": "d3f456abc789",
  "form": {
    "id": "a1b2c3d4e5",
    "name": "Contact Form"
  },
  "submission": {
    "id": "x9y8z7w6v5",
    "created_at": "2025-03-15T14:30:00.000Z",
    "data": {
      "name": "Alex",
      "email": "alex@example.com",
      "message": "Hello there"
    },
    "is_test": false,
    "is_spam": false
  }
}

form.spam

Fires when TorchWarden flags a submission as spam. Use this event to log or review suspicious submissions without cluttering your main pipeline.

Example payload


{
  "event": "form.spam",
  "timestamp": "2025-03-15T14:31:00.000Z",
  "delivery_id": "e7a123def456",
  "form": {
    "id": "a1b2c3d4e5",
    "name": "Contact Form"
  },
  "submission": {
    "id": "q2w3e4r5t6",
    "created_at": "2025-03-15T14:31:00.000Z",
    "data": {
      "name": "Buy cheap meds",
      "email": "spammer@example.net",
      "message": "Click here for great deals"
    },
    "is_test": false,
    "is_spam": true
  }
}

form.test

Fires for test submissions: either from the Send Test button in the dashboard, or when a form submission includes _test=true. Use this event to verify your endpoint integration without affecting real data.

Example payload


{
  "event": "form.test",
  "timestamp": "2025-03-15T14:32:00.000Z",
  "delivery_id": "f8b234cde567",
  "form": {
    "id": "test_form_id",
    "name": "Test Form"
  },
  "submission": {
    "id": "test_submission_id",
    "created_at": "2025-03-15T14:32:00.000Z",
    "data": {
      "name": "Test User",
      "email": "test@formtorch.com",
      "message": "This is a FormTorch webhook test payload."
    },
    "is_test": true,
    "is_spam": false
  }
}

Payload field reference

Field	Type	Description
`event`	string	Event name: `form.submitted`, `form.spam`, or `form.test`
`timestamp`	string	ISO 8601 timestamp when the delivery was created
`delivery_id`	string	Unique ID for this delivery; matches `X-FormTorch-Delivery` header
`form.id`	string	ID of the form that received the submission
`form.name`	string	Display name of the form
`submission.id`	string	Unique submission ID
`submission.created_at`	string	ISO 8601 timestamp when the submission was received
`submission.data`	object	Submitted field values (reserved `_*` fields excluded)
`submission.is_test`	boolean	`true` for test submissions
`submission.is_spam`	boolean	`true` for spam submissions