Outlign

Outlign API

v1.0 Documentation

Webhooks

Webhooks allow your application to receive real-time notifications when events occur in Outlign. When an event fires, Outlign sends an HTTP POST request to your configured URL with the event payload.

How Webhooks Work

Webhook subscriptions are configured per company and can listen for specific event types. When a matching event occurs, Outlign delivers a JSON payload to your endpoint via HTTP POST.

Webhook Delivery Flow

1

Event Occurs

An action triggers an event in Outlign (e.g., a task is created)

2

Subscription Matched

Outlign checks for active webhook subscriptions matching the event type and company

3

Payload Delivered

An HTTP POST request is sent to your endpoint with the event data as JSON

Available Event Types

The following webhook event types are available for subscription:

Event Type Description
task.created Fires when a new task is created
task.completed Fires when a task is marked as completed
task.due_date_updated Fires when a task's due date is changed
phase.updated Fires when a phase is updated
milestone.created Fires when a new milestone is created
milestone.updated Fires when a milestone is updated

Webhook Payload Format

Webhook payloads are delivered as JSON via HTTP POST. The payload contains the full resource data for the affected entity at the time of the event.

Task Event Payload

Sent for task.created, task.completed, and task.due_date_updated events. 

{
  "id": 123,
  "title": "Design homepage wireframe",
  "phase_id": 456,
  "completed": false,
  "due_date": "2023-02-15",
  "order": 1,
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-01T12:00:00Z",
  "phase": {
    "id": 456,
    "title": "Design Phase",
    "project": {
      "id": 789,
      "title": "Website Redesign",
      "client": {
        "id": 101,
        "title": "Acme Corporation",
        "company_id": 202
      }
    }
  }
}

Phase Event Payload

Sent for phase.updated events. 

{
  "id": 456,
  "title": "Design Phase",
  "project_id": 789,
  "is_internal": false,
  "due_date": "2023-03-15T23:59:59Z",
  "colour": "#9177FB",
  "order": 1,
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-15T14:30:00Z",
  "project": {
    "id": 789,
    "title": "Website Redesign",
    "client": {
      "id": 101,
      "title": "Acme Corporation",
      "company_id": 202
    }
  }
}

Milestone Event Payload

Sent for milestone.created and milestone.updated events. 

{
  "id": 42,
  "title": "Design Review",
  "description": "Final design review with stakeholders",
  "color": "#9177FB",
  "due_date": "2023-03-15T00:00:00.000000Z",
  "is_completed": false,
  "milestoneable_type": "App\\Models\\Project",
  "milestoneable_id": 789,
  "project": {
    "id": 789,
    "title": "Website Redesign"
  },
  "client": {
    "id": 101,
    "title": "Acme Corporation"
  },
  "company": {
    "id": 202,
    "title": "Design Studio Inc"
  },
  "created_at": "2023-01-01T12:00:00.000000Z",
  "updated_at": "2023-01-01T12:00:00.000000Z"
}

Best Practices

Respond Quickly: Your endpoint should return a 2xx status code within a few seconds. Process webhook data asynchronously if your handling logic is complex.

Handle Duplicates: In rare cases, the same event may be delivered more than once. Use the resource ID and timestamps to detect and handle duplicate deliveries.

Verify Payloads: Always validate incoming webhook data before processing. Check that resource IDs and types match expected values.