Ezylegal

Webhook Events

This page documents all webhook events that ezylegal can send to your application.

Event List

| Event | Description | Priority | |-------|-------------|----------| | session.accessed | Customer first opened the form | Normal | | session.section_completed | A section was completed | Normal | | session.completed | Form fully submitted | High | | session.pdf_ready | PDF document generated | High | | session.expired | Session expired | Normal |

session.accessed

Triggered when a customer opens the session link for the first time.

Payload

{
  "event": "session.accessed",
  "session_id": "sess_abc123xyz",
  "timestamp": "2024-01-15T11:00:00Z",
  "data": {
    "session_id": "sess_abc123xyz",
    "accessed_at": "2024-01-15T11:00:00Z",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
    "ip_address": "203.0.113.42"
  }
}

Use Cases

  • Update your UI to show the session is in progress
  • Start a timer for follow-up reminders
  • Log customer engagement metrics

session.section_completed

Triggered each time the customer completes a section of the form.

Payload

{
  "event": "session.section_completed",
  "session_id": "sess_abc123xyz",
  "timestamp": "2024-01-15T11:30:00Z",
  "data": {
    "session_id": "sess_abc123xyz",
    "section": "personal_details",
    "section_number": 1,
    "sections_total": 7,
    "sections_completed": 1,
    "progress_percentage": 14
  }
}

Section Names

| Section | Description | |---------|-------------| | personal_details | Name, contact, occupation | | income | Employment and other income | | assets | Property, vehicles, accounts | | liabilities | Mortgages, loans, debts | | expenses | Monthly expenditure | | documents | Supporting documents | | declaration | Final review and signature |

Use Cases

  • Show real-time progress to your team
  • Send encouragement notifications to the customer
  • Identify where customers are getting stuck

session.completed

Triggered when the customer submits the completed form.

Payload

{
  "event": "session.completed",
  "session_id": "sess_abc123xyz",
  "timestamp": "2024-01-16T14:22:00Z",
  "data": {
    "session_id": "sess_abc123xyz",
    "completed_at": "2024-01-16T14:22:00Z",
    "form_type": "financial_statement",
    "reference_id": "case-12345",
    "duration_minutes": 87,
    "summary": {
      "total_assets": 1015000,
      "total_liabilities": 468000,
      "net_worth": 547000
    }
  }
}

Use Cases

  • Fetch the complete form data via API
  • Notify your team that a form is ready for review
  • Update case status in your system
  • Trigger downstream workflows

session.pdf_ready

Triggered when the PDF document has been generated (usually within 30 seconds of completion).

Payload

{
  "event": "session.pdf_ready",
  "session_id": "sess_abc123xyz",
  "timestamp": "2024-01-16T14:22:30Z",
  "data": {
    "session_id": "sess_abc123xyz",
    "pdf_url": "https://api.ezy-forms.com.au/v1/sessions/sess_abc123xyz/pdf",
    "file_size_bytes": 125432,
    "page_count": 8
  }
}

Use Cases

  • Automatically download and store the PDF
  • Email the PDF to relevant team members
  • Attach the PDF to a case management system

Note

The pdf_url requires authentication. Use your API key to download:

curl https://api.ezy-forms.com.au/v1/sessions/sess_abc123xyz/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o statement.pdf

session.expired

Triggered when a session expires without being completed.

Payload

{
  "event": "session.expired",
  "session_id": "sess_abc123xyz",
  "timestamp": "2024-02-14T10:30:00Z",
  "data": {
    "session_id": "sess_abc123xyz",
    "expired_at": "2024-02-14T10:30:00Z",
    "was_accessed": true,
    "progress_percentage": 43,
    "last_activity_at": "2024-01-20T16:45:00Z"
  }
}

Use Cases

  • Send a reminder to the customer
  • Create a new session with extended deadline
  • Mark the case as requiring follow-up
  • Archive incomplete submission

Handling Multiple Events

Events may arrive in rapid succession. Your handler should be prepared:

async function handleWebhook(event) {
  // Use a queue for reliable processing
  await queue.add('process-webhook', {
    eventType: event.event,
    sessionId: event.session_id,
    data: event.data,
    receivedAt: Date.now(),
  });
}

// Process from queue
queue.process('process-webhook', async (job) => {
  const { eventType, sessionId, data } = job.data;

  // Fetch current session state
  const session = await db.sessions.findByExternalId(sessionId);

  // Only process if state transition is valid
  if (isValidTransition(session.status, eventType)) {
    await processEvent(eventType, session, data);
  }
});

Event Ordering

Events are generally delivered in order, but network conditions may cause out-of-order delivery. Always check timestamps:

async function handleSectionCompleted(sessionId, data) {
  const session = await db.sessions.find(sessionId);

  // Only update if this is more recent
  if (data.timestamp > session.lastEventAt) {
    await session.update({
      progress: data.progress_percentage,
      lastEventAt: data.timestamp,
    });
  }
}

Related Pages