KanbanGit/docs/releases/v0.5-webhook-notification/04-generic-webhook-delivery.md

04 Generic Webhook Delivery

Implementation guide: Ticket Implementation Guide

Branch

codex/v0.5-webhook-notification/04-generic-webhook-delivery

Start this branch from codex/v0.5-webhook-notification/03-ticket-status-changed-trigger.

Goal

Deliver ticket_status_changed notifications to classic JSON webhook URLs.

Requirements

• Implement queued delivery for notification actions using the webhook channel.
• Send an HTTP POST JSON request to the configured webhook URL.
• Include a structured payload suitable for n8n:
  • event type
  • project object
  • ticket object
  • actor object or null
  • from status object
  • to status object
  • ticket URL
  • occurred timestamp
• Use Laravel's HTTP client with a sensible timeout.
• Configure job retry/backoff so temporary webhook failures can retry.
• Persist delivery logs for success and failure.
• Store HTTP status and a short response or error excerpt when available.
• External delivery failures must not roll back ticket moves.

Acceptance Criteria

• Webhook actions receive a JSON POST for ticket status changes.
• The payload contains enough context for n8n to route and format follow-up automation.
• Successful responses mark the delivery log as succeeded.
• Failed responses or connection errors mark the delivery attempt as failed or retryable according to the job state.
• Discord actions are not delivered by this ticket.

Tests

• HTTP fake tests asserting method, URL, headers, and JSON payload.
• Tests for successful delivery log updates.
• Tests for non-2xx responses and connection failures.
• Queue/job tests for retry/backoff configuration where practical.
• Regression test that ticket moves still succeed when webhook delivery fails later.

Verification

• vendor/bin/pint --dirty --format agent
• php artisan test --compact tests/Feature/Notifications tests/Feature/Projects
• git diff --check

Commit And Push

• Commit only this ticket's changes.
• Push with git push origin codex/v0.5-webhook-notification/04-generic-webhook-delivery.

Out of Scope

• Discord delivery
• Custom webhook headers or signing secrets
• Delivery attempt UI
• User bell notifications
• Unread counters
• Slack, Teams, email, or other channels
• Incoming webhooks
• API or MCP management endpoints