About

Workflow webhooks deliver real-time notifications to your application when key events occur in the workflow lifecycle. Subscribe to the events you care about, point them at your endpoint, and Interactly will POST a structured payload to your system — immediately, reliably, and with automatic retry on failure.

Workflow webhooks are outbound — Interactly sends events to your endpoint. For triggering workflows from external events, see Scheduled & Triggered Workflows.

Available Events

workflow_created

Fired when a new workflow is created in your team’s account.

workflow_updated

Fired when a workflow’s configuration, version, or settings are modified.

workflow_deleted

Fired when a workflow is permanently deleted.

workflow_run_started

Fired the moment a workflow execution begins — regardless of trigger type (manual, scheduled, or triggered).

workflow_run_completed

Fired when a workflow run reaches a final state — completed, failed, or cancelled — with full run output included.

Configuring a Webhook

Webhooks are configured via the API. Use the POST /workflow-webhooks endpoint with the following fields:

name — a label for this webhook (required)
url — the HTTPS endpoint where Interactly should deliver event payloads; must be publicly accessible and return a 2xx status to acknowledge receipt
actions — list of lifecycle events to subscribe to; choose one or all five
enabled — whether the webhook is active (default: true)
bearer_token — optional token sent as an Authorization: Bearer header on every request, allowing your endpoint to verify the request originated from Interactly
timeout_seconds — how long Interactly waits for a response before treating it as a failure (1–60 seconds, default 10)
max_retries — how many times to retry a failed delivery (0–10, default 3)
retry_backoff_seconds — wait time in seconds between retries (1–300 seconds, default 10)

Event Payload Examples

workflow_created

{
  "event": "workflow_created",
  "workflow": {
    "id": "wf_abc123",
    "teamId": "team_001",
    "name": "Patient Intake Flow",
    "activeVersionNumber": 0,
    "createdAt": "2026-04-01T09:00:00.000Z",
    "updatedAt": "2026-04-01T09:00:00.000Z"
  }
}

workflow_updated

{
  "event": "workflow_updated",
  "workflow": {
    "id": "wf_abc123",
    "teamId": "team_001",
    "name": "Patient Intake Flow",
    "activeVersionNumber": 2,
    "createdAt": "2026-04-01T09:00:00.000Z",
    "updatedAt": "2026-04-15T14:32:00.000Z"
  }
}

workflow_deleted

{
  "event": "workflow_deleted",
  "workflow": {
    "id": "wf_abc123",
    "teamId": "team_001",
    "name": "Patient Intake Flow",
    "deletedAt": "2026-04-20T11:00:00.000Z"
  }
}

workflow_run_started

{
  "event": "workflow_run_started",
  "workflow": {
    "id": "wf_abc123",
    "teamId": "team_001",
    "name": "Patient Intake Flow"
  },
  "run": {
    "id": "run_xyz789",
    "versionNumber": 2,
    "status": "in_progress",
    "triggeredBy": "manual",
    "startedAt": "2026-04-20T10:15:00.000Z"
  }
}

workflow_run_completed

{
  "event": "workflow_run_completed",
  "workflow": {
    "id": "wf_abc123",
    "teamId": "team_001",
    "name": "Patient Intake Flow"
  },
  "run": {
    "id": "run_xyz789",
    "versionNumber": 2,
    "status": "completed",
    "triggeredBy": "manual",
    "startedAt": "2026-04-20T10:15:00.000Z",
    "completedAt": "2026-04-20T10:17:32.000Z",
    "output": {
      "collectedInformation": {
        "patientName": "Jane Doe",
        "appointmentDate": "2026-05-01",
        "insuranceProvider": "BlueCross"
      }
    }
  }
}

Retry Behaviour

If your endpoint does not return a 2xx status — or does not respond within the timeout window — Interactly will automatically retry the delivery using exponential backoff.

Retry Schedule

Retries are spaced with increasing intervals — the first retry happens quickly, with subsequent retries spaced progressively further apart. This prevents overwhelming a temporarily unavailable endpoint while still ensuring eventual delivery.All delivery attempts — successful and failed — are logged in the webhook’s Delivery Logs for inspection.

Delivery Logs

Every delivery attempt is recorded with:

Timestamp of the attempt
HTTP status code returned by your endpoint
Response body (truncated if large)
Whether the delivery succeeded or will be retried

Access delivery logs from the Webhooks tab on your workflow.

Handling Duplicates

In rare cases — such as a network timeout where your server processed the request but the acknowledgement was lost — Interactly may deliver the same event more than once. Design your webhook handler to be idempotent, using the run.id or workflow.id as a deduplication key.

Use a bearer token to verify that payloads are genuinely from Interactly before processing them. Reject any requests that do not include the expected token in the Authorization header.

Best Practices

Respond quickly, process asynchronously

Return a 200 OK immediately upon receiving a webhook payload, then process the event asynchronously. If your handler takes too long to respond, Interactly will treat it as a timeout and retry.

Use run_completed for downstream automation

The workflow_run_completed event includes the full run output and collected information. This is the most useful event for triggering downstream actions — updating a CRM record, sending a notification, or initiating a follow-up workflow.

Monitor delivery logs regularly

Check delivery logs periodically to catch silent failures — cases where your endpoint is returning errors and retries are being exhausted without anyone noticing.

API Reference

List Workflow Webhooks

GET /workflow-webhooks Retrieve all webhook subscriptions for your team

Create Webhook

POST /workflow-webhooks Register a new webhook endpoint and subscribe to events

Update Webhook

PATCH /workflow-webhooks/:id Modify an existing webhook’s URL, events, or headers

Delete Webhook

DELETE /workflow-webhooks/:id Remove a webhook subscription

Next Steps

Scheduled & Triggered Workflows

Set up automated execution so webhook events fire without manual runs

Workflow Versioning

Receive version activation events to track deployments

Building a Workflow

Go back to the workflow builder guide

Simulation

Test your workflow before enabling live webhook delivery

General

Quickstart

Calls

Campaigns

Workflows

Assistant Tools

Webhooks

Vendors

Prompts

Workflow Webhooks

About

Available Events

workflow_created

workflow_updated

workflow_deleted

workflow_run_started

workflow_run_completed

Configuring a Webhook

Event Payload Examples

Retry Behaviour

Best Practices

API Reference

List Workflow Webhooks

Create Webhook

Update Webhook

Delete Webhook

Next Steps

Scheduled & Triggered Workflows

Workflow Versioning

Building a Workflow

Simulation

​About

​Available Events

workflow_created

workflow_updated

workflow_deleted

workflow_run_started

workflow_run_completed

​Configuring a Webhook

​Event Payload Examples

​Retry Behaviour

​Best Practices

​API Reference

List Workflow Webhooks

Create Webhook

Update Webhook

Delete Webhook

​Next Steps

Scheduled & Triggered Workflows

Workflow Versioning

Building a Workflow

Simulation

About

Available Events

Configuring a Webhook

Event Payload Examples

Retry Behaviour

Best Practices

API Reference

Next Steps