Webhook Events & Payloads

Every webhook delivery sends a JSON payload to your endpoint. All payloads share a common envelope format with event-specific data inside.

Common Envelope


{
  "id": "evt_abc123",
  "event": "process_run.completed",
  "timestamp": "2024-01-15T14:45:00Z",
  "test": false,
  "data": { ... }
}

Field	Description
`id`	Unique event ID
`event`	Event type string
`timestamp`	ISO 8601 timestamp
`test`	`true` if this is a test delivery
`data`	Event-specific payload (see below)

HTTP Headers

Every webhook request includes these headers:


Content-Type: application/json
X-Webhook-Event: process_run.completed
X-Webhook-Id: evt_abc123

process_run.created

Fires when someone starts a new process instance.


{
  "id": "evt_abc123",
  "event": "process_run.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "test": false,
  "data": {
    "instance_id": "inst_456",
    "template_id": "tmpl_789",
    "title": "Client Onboarding - Acme Corp",
    "started_by": {
      "user_id": "uid_abc",
      "email": "user@example.com",
      "is_guest": false
    },
    "started_at": "2024-01-15T10:30:00Z",
    "due_date": null,
    "is_shared": false,
    "task_count": 5
  }
}

process_run.completed

Fires when all tasks in a process instance are completed.


{
  "id": "evt_def456",
  "event": "process_run.completed",
  "timestamp": "2024-01-15T14:45:00Z",
  "test": false,
  "data": {
    "instance_id": "inst_456",
    "template_id": "tmpl_789",
    "title": "Client Onboarding - Acme Corp",
    "started_by": {
      "user_id": "uid_abc",
      "email": "user@example.com",
      "is_guest": false
    },
    "started_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T14:45:00Z"
  }
}

process_step.completed

Fires when an individual task is completed. Only fires for tasks with “Send webhook on completion” enabled in the process editor.


{
  "id": "evt_ghi789",
  "event": "process_step.completed",
  "timestamp": "2024-01-15T12:00:00Z",
  "test": false,
  "data": {
    "task_id": "task_101",
    "instance_id": "inst_456",
    "title": "Collect Client Information",
    "completed_at": "2024-01-15T12:00:00Z",
    "completed_by": {
      "user_id": "uid_abc",
      "email": "user@example.com",
      "is_guest": false
    },
    "assigned_to": {
      "user_id": "uid_def",
      "email": "assignee@example.com",
      "is_guest": false
    },
    "due_date": "2024-01-22T17:00:00Z",
    "type": "task",
    "form_fields": [
      {
        "id": "el_1",
        "type": "shortText",
        "label": "Client Name",
        "value": "Acme Corp"
      },
      {
        "id": "el_2",
        "type": "email",
        "label": "Contact Email",
        "value": "jane@acme.com"
      },
      {
        "id": "el_3",
        "type": "dropdown",
        "label": "Plan Type",
        "value": "Enterprise"
      }
    ]
  }
}

Form Fields

The form_fields array includes all input fields from the completed task — text, email, number, dropdown, multi-choice, date, checkbox, and file uploads. Display-only elements (static text, images, line breaks) are excluded.

Form field data is captured at the moment of task completion. If fields are later edited, the webhook payload will reflect the values at the time the task was originally completed.

Guest Users

For guest users (people running the process without a NextStep account), the is_guest field will be true. Their email is resolved from the process invitation if available, otherwise it may be null.