# REVEALDI RACF observe-only PHP pack

Staging intake:

```
POST https://api.revealdi.com/v1/submissions
```

This pack is **OBSERVE_ONLY**. Implio remains the live website decision. Do not hide content, restore content, change visibility, or take a profile offline from a REVEALDI result.

Credentials are supplied separately. This ZIP does not contain API keys, webhook secrets, `.env` files, or console access.

## Files

| File | Use |
| --- | --- |
| `revealdi_observe_submit.php` | PHP 7.4 helper: HMAC sign + cURL POST |
| `revealdi_observe_usage.php` | Queue-oriented example with placeholders |
| `revealdi_observe_webhook.php` | PHP 7.4 `observation.result` receiver. Not an Implio webhook. |
| `racf-observe-handoff.md` | Request/response contract and callback schema |
| `README.md` | This file |

## Configuration

Set in the RACF secret store or environment. Do not commit them.

- `REVEALDI_KEY_ID` — `X-Panpad-Key-Id`
- `REVEALDI_SECRET` — inbound HMAC secret (UTF-8)
- `REVEALDI_WEBHOOK_SECRET` — outbound webhook HMAC secret (shown once at subscribe). Not `REVEALDI_SECRET`.

Optional helper keys: `base_url` (default `https://api.revealdi.com`), `timeout` (default 15 seconds).

Image hosts must be allowlisted on the REVEALDI client. Send `https` photo URLs the REVEALDI server can GET. `blob:`, `data:`, and `file:` URLs are rejected.

## Run from a background job

Call `revealdi_submit()` from a queue worker after (or beside) the existing Implio send.

- Do **not** block the Implio HTTP path on REVEALDI.
- If REVEALDI is slow or down, continue Implio unchanged.
- HTTP **201** (new) or **200** (same source event replayed) means the event was **accepted**, not that evaluation finished.
- The evaluation arrives later as `observation.result`.

## Retries

- Replay of the same `X-Panpad-Request-Id` is rejected. Each HTTP attempt needs a new UUID. The helper generates one per attempt.
- The helper retries 408, 429, 5xx, connect/read timeout, and connection reset. Backoff 5 / 15 / 45 / 90 seconds. Default max 5 attempts.
- Keep the same `client_submission_id` for the same source event. Same body → 200. Different body → 409.
- Clock skew allowance is 300 seconds.
- Recommended image URL lifetime: at least 20 minutes after POST so ingest retries can finish.

## Callback setup

1. Copy `revealdi_observe_webhook.php` to an HTTPS path that does **not** redirect (use `www` if the apex host 301s).
2. Ask REVEALDI to subscribe that exact URL to **`observation.result` only**.
3. Verify the existing webhook HMAC (`docs/webhooks.md` in the main repo; summary is in the handoff).
4. Dedupe on `event_id`. HTTP 2xx means the callback was accepted, not that a website action was applied.
5. Record the payload for internal comparison. Do not apply it to the website or show it to users.

Until the callback URL is confirmed, do not enable mirrored production traffic.