Skip to main content

​
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

{
  "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"
  }
}

{
  "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"
  }
}

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

{
  "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"
  }
}

{
  "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.
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.
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.
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

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.
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.
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