# 07 Webhooks

Webhook design goals:

- Multi-merchant event routing
- Idempotent processing
- Retry-safe handlers
- Event logging and replay support
- Signature verification (`X-Uber-Signature` HMAC SHA256 with client secret)

Current ingestion endpoint: `POST /api/v1/webhooks/uber`

Acknowledgement behavior:

- Valid webhook events are acknowledged with `200` and empty body
- Duplicate retries are de-duplicated and still acknowledged with `200`

Common event types handled:

- `orders.notification`
- `orders.failure`
- `orders.release`
- `orders.scheduled.notification`
- `orders.cancel`
- `delivery.state_changed`
- `store.provisioned`
- `store.deprovisioned`
- `store.menu_refresh_request`
- `store.status.changed`
- `eats.report.success`

Menu refresh handling:

- On `store.menu_refresh_request`, wrapper records the request on the mapped Uber store connection.
- Persisted fields include:
  - `last_menu_refresh_requested_at`
  - `last_menu_refresh_webhook_uuid`
  - `last_webhook_environment` (from `X-Environment`)

Retail fulfillment follow-up:

- On `orders.fulfillment_issues.resolved`, fetch updated order details and inspect customer acknowledgment before next action.