# Workflow — magento-orderwebhook

> **Last verified:** 2026-02-26 (Europe/London)
> **Owner:** Engineering
> **Related:** [architecture.md](architecture.md) | [API.md](API.md)

---

## Local Development Setup

### Prerequisites

- PHP >= 7.4
- Magento 2 development environment (luma or Hyvä)
- Composer

### Install

```bash
# From Magento root
composer require portalpeople/magento-orderwebhook
bin/magento module:enable PortalPeople_OrderWebhook
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush
```

### Configuration

Configure via Magento admin: **Stores → Configuration → [PortalPeople] → NGauge Webhook**

| Setting | Path | Notes |
|---------|------|-------|
| Enable Webhook | `order_webhook/general/enabled` | Must be `1` for any webhook to fire |
| API Endpoint URL | `order_webhook/general/api_url` | Full NGauge endpoint URL |
| API Key | `order_webhook/general/api_key` | Stored encrypted |
| Request Timeout | `order_webhook/general/timeout` | Default: 30s |
| Retry Attempts | `order_webhook/general/retry_attempts` | Default: 3 |
| Enable Logging | `order_webhook/general/log_enabled` | Default: 1 |
| NGauge Base URL | `order_webhook/ngauge/base_url` | Default: `https://ahshub.portalpeople.app` |
| Response to Comment Only | `order_webhook/ngauge/comment_only` | When `1`, NGauge fields not written to DB |

### Test Webhook

Use the CLI command to verify connectivity:

```bash
bin/magento order:webhook:test ORDER_INCREMENT_ID
```

This sends a `test_webhook` event for the specified order and prints the masked config.

---

## Known Issues

| Issue | Severity | Details |
|-------|----------|---------|
| ObjectManager usage for `EncryptorInterface` | MEDIUM | `WebhookSender::sendRequest()` uses `ObjectManager::getInstance()` — bypasses DI, prevents unit testing |
| Incorrect `extra.bootstrap` in `composer.json` | MEDIUM | References `PortalPeople\\NgaugeBackupSql\\Module` — likely copy-paste error |
| Version mismatch | LOW | `composer.json` v1.0.15 vs `module.xml` `setup_version="1.0.0"` |
| Deprecated `Magento\Framework\Registry` | LOW | Used in `NgaugeFields` block to retrieve current order |
| Once `ngauge_order_id` is set, admin resend button disappears | NOTE | CLI-only resend path unless field manually cleared |
| No PHPUnit tests | LOW | No automated regression protection |
| `src/README.md` version history inaccurate | NOTE | Documents `order_updated` as firing on "processing, complete, or shipped" — code fires only on `processing` |

---

## Resend Webhook

### Via Admin UI

1. Navigate to **Sales → Orders → [Order]**.
2. In the NGauge section, click **"Send to NGauge"** (only visible if `ngauge_order_id` is not set).
3. The page reloads; check the order history comments for the result.

### Via CLI

```bash
bin/magento order:webhook:test ORDER_INCREMENT_ID
```

---

## PR Checklist

- [ ] No non-documentation files modified unless Implementation Mode is explicitly enabled
- [ ] `docs/architecture.md` updated if observer logic, payload fields, or integration points changed
- [ ] `docs/API.md` updated if webhook payload fields or event types changed
- [ ] `docs/BOUNDARIES.md` updated if new external dependencies added
- [ ] `docs/DATA_OWNERSHIP.md` updated if new PII/special-category data is sent in webhook payload
- [ ] `docs/OBSERVABILITY.md` updated if logging or error handling changes
- [ ] `docs/GDPR.md` reviewed if new personal data is added to webhook payload
- [ ] ADR created if architectural decision made (e.g., DB table change, new integration)
- [ ] Mermaid diagrams updated and standards-compliant
- [ ] Version strings aligned: `composer.json`, `module.xml`
- [ ] All `UNKNOWN — Requires Clarification` tokens resolved or escalated

---

## Confirmed Facts

- Install follows standard Magento 2 `composer require` + `setup:upgrade` workflow.
- CLI command `order:webhook:test` is available for connectivity testing.
- No PHPUnit test suite exists — all verification is manual.

---

## Unknowns

1. `UNKNOWN — Requires Clarification`: Is there a staging NGauge environment for testing? What URL does it use?
2. `UNKNOWN — Requires Clarification`: Is there a local Magento development environment with magento-deliverydates installed?

---

## Evidence

- `/modules/magento-orderwebhook/composer.json`
- `/modules/magento-orderwebhook/src/etc/module.xml`
- `/modules/magento-orderwebhook/src/etc/config.xml`
- `/modules/magento-orderwebhook/src/etc/adminhtml/system.xml`
- `/modules/magento-orderwebhook/src/Console/Command/TestWebhookCommand.php`
- `/modules/magento-orderwebhook/src/Model/WebhookSender.php`
- `/modules/magento-orderwebhook/src/README.md`
